API 驗證

Rivya API 使用 API key 進行伺服器對伺服器的存取。

API key 不等同於瀏覽器登入工作階段。請不要把 cookie、Better Auth session state 或個人瀏覽器 token 當作公開 API 憑證使用。

Header 格式

在 Authorization header 中傳送 key：

Authorization: Bearer rvya_sk_...

完整 key 只會在建立時顯示一次。Rivya 會儲存 hash 和可見 prefix，而不是完整密鑰。

建立 Key

1. 登入 Rivya。
2. 開啟 API Keys 設定。
3. 使用你需要的 scopes 建立 key。
4. 立即複製完整 key。
5. 將它存放在伺服器端 secret manager 或環境變數中。

不要把 key 放在客戶端 JavaScript、行動應用程式套件、公開 repo、analytics 事件或日誌中。

目前 Scopes

第一版文件記錄了這些 scopes：

• models:read
• generations:create
• generations:read
• files:create
• files:read
• credits:read
• webhooks:manage
• chat:create
• chat:read

在 Settings 中新建立的 key 預設包含已記錄的 scopes。較早建立的 key 可能需要重新建立，才能使用 Files API、API Webhooks 或 Chat API。

撤銷與輪換

如果 key 外洩：

1. 從 Settings 撤銷舊 key。
2. 建立新 key。
3. 更新伺服器端 secret。
4. 使用 GET /api/v1/credits 確認新 key 可用。
5. 從建置系統、日誌和部署變數中移除舊 key。

已撤銷的 key 會回傳 api_key_revoked。

驗證錯誤

常見驗證錯誤：

• api_key_missing
• api_key_invalid
• api_key_revoked
• api_key_expired
• api_scope_denied
• public_api_disabled

完整公開錯誤表請見 API 錯誤與限制。

相關頁面

• API 快速開始
• API 點數
• API 錯誤與限制
• Rivya 的驗證與存取