API 鉴权
使用 Bearer API Key 验证 Rivya API 请求,了解权限范围、一次性展示、禁用和轮换。
最近审阅于 2026年11月5日
Rivya API 使用 API Key 做服务端到服务端访问。
API Key 不等于浏览器登录态。不要把 cookie、Better Auth session 或个人浏览器 token 当成公开 API 凭据。
Header 格式
把 key 放在 Authorization header:
Authorization: Bearer rvya_sk_...完整 key 只会在创建时展示一次。Rivya 保存 hash 和可见 prefix,不保存完整密钥。
创建 Key
登录 Rivya。
打开 API Keys 设置。
输入 1–80 个字符的名称并创建 Key。设置页固定授予下列全部权限,没有权限选择器。
立即复制完整 key。
保存到服务端 secret manager 或环境变量中。
不要把 key 放进客户端 JavaScript、移动端包、公开仓库、analytics 事件或日志。
当前 Scope
设置页创建的新 Key 固定包含九项权限,不能选择子集或修改既有 Key 的权限。
models:read— 包含在新 Key 中;模型列表目前公开,不检查此权限。generations:create— 用可调用模型提交生成。generations:read— 读取和刷新所属账户的生成任务。files:create— 上传所属账户支持的参考文件。files:read— 读取所属账户可用文件的元数据。credits:read— 读取当前账户余额。webhooks:manage— 管理端点、签名密钥和投递记录,还需开启 Webhook 功能。chat:create— 向支持的聊天模型发送普通或串流请求。chat:read— 列出所属账户由 API 创建的聊天会话并读取已提交消息。
Key 使用创建账户的积分与资源归属,不能访问其他账户的任务、文件或聊天。旧 Key 若缺少文件、聊天或 Webhook 权限,需创建替代 Key 并更新服务端配置;设置页不会为旧 Key 追加权限。
Key 有效期
在设置中创建的 Key 当前不会自动过期,表单也不能设置有效期。若某个 Key 配有过期时间,受保护请求从该时刻起返回 api_key_expired。
Key 被撤销或所属账户被封禁后也无法授权请求。有效权限不能开启已禁用的 API 功能。
禁用和轮换
撤销会拒绝后续受保护请求,不会取消已受理的生成任务。计划轮换时,先创建并安全保存替代 Key,更新服务端配置,用 GET /api/v1/credits 验证后再撤销旧 Key。设置页提供创建与撤销,不会原地替换。余额查询成功仅验证鉴权及 credits:read,不证明生成、文件、聊天或 Webhook 权限。泄露时应先撤销,再按下列步骤替换。
如果 key 泄漏:
在 API 密钥设置撤销泄露的旧 Key。
创建新 key。
更新服务端 secret。
用
GET /api/v1/credits确认新 key 可用。从构建系统、日志和部署变量中移除旧 key。
被禁用的 key 会返回 api_key_revoked。
鉴权错误
受保护端点返回含 code、message 及可用时 requestId 的 error 对象。401 的 api_key_missing 表示缺少可用 Bearer token,api_key_invalid 表示格式、前缀或密钥与现有账户不匹配,api_key_revoked 表示撤销或账户封禁,api_key_expired 表示已到配置的过期时刻。403 的 api_scope_denied 表示缺少权限,应替换旧 Key,设置页不能修改其权限。503 的 public_api_disabled 表示 API 已关闭或哈希配置不可用,Webhook 独立开关关闭也使用此码;换 Key 不能开启功能。
常见鉴权错误:
api_key_missingapi_key_invalidapi_key_revokedapi_key_expiredapi_scope_deniedpublic_api_disabled
完整公共错误表见 API 错误码与限制。
