跳到主要内容

鉴权

每个调用都在 Authorization 请求头里带一个凭证：

Authorization: Bearer <credential>

凭证有两种，分别给两类调用方使用。每个接口只接受其中一种：API 参考在每个接口上都注明了。

凭证持有方可调用的接口
项目密钥你的后端终端用户管理：/v1/users 与 /v1/users/{user_id}/tokens
用户令牌你的应用，对应某一个终端用户终端用户能做的一切：会话、消息、事件、文件、生成、语音、转写、/v1/me

把用户令牌用在管理接口上，会被拒绝并返回 403 permission_denied。把项目密钥用在终端用户接口上，会被拒绝并返回 401 invalid_token，和任何不是有效用户令牌的凭证一样。

项目密钥​

项目密钥代表你的项目。创建项目时会在控制台里得到第一个，之后可以在项目的密钥页面创建更多。控制台只在创建密钥时显示一次完整内容；之后只显示开头几个字符，方便区分不同的密钥。

  • 密钥只放在你的服务器上。任何拿到密钥的人都能创建、停用和删除你的终端用户，并为他们签发令牌。
  • 每个服务或每个环境用一个密钥，这样作废其中一个不会影响其他。
  • 轮换密钥：先创建新密钥并部署上线，再作废旧密钥。被作废的密钥此后会被拒绝，返回 401 invalid_secret。

项目被停用期间，它的密钥会被拒绝并返回 403 project_disabled，它的用户令牌会被拒绝并返回 401 project_disabled。

用户令牌​

用户令牌让某一个终端用户的应用以该用户的身份调用 API。令牌由你的后端签发：

curl -s "$NEWEYES_API_BASE/v1/users/$USER_ID/tokens" -X POST \
  -H "Authorization: Bearer $NEWEYES_PROJECT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

用户的第一个令牌也可以在创建用户时一并拿到：创建时传 issue_token: true（想要别的有效期再加 expires_in），响应里的 token 就是这个令牌。

  • 有效期。 expires_in 以秒为单位，取值 60 到 86,400（24 小时）；不填为一小时。任何令牌的有效期都不超过 24 小时，所以从应用里被拷走的令牌也会自行失效。
  • 续期。 在旧令牌过期前签发新令牌——比如应用启动时，或某个调用返回 401 token_expired 时。签发新令牌不影响之前签发的令牌。
  • 作废。 DELETE /v1/users/{user_id}/tokens 会作废该用户此前签发的全部令牌（例如怀疑泄露时）；此后这些令牌都会被拒绝，返回 401 invalid_token。之后新签发的令牌照常可用。控制台的作废全部令牌会一次性对项目的所有终端用户做同样的事。
  • 停用。 被停用用户的令牌会失效（401 user_disabled），重新启用之前也无法为其签发新令牌。

GET /v1/me 返回令牌所属的终端用户及其项目，是应用检查令牌是否仍然有效的低成本方式。

语音连接​

语音通话不会在 WebSocket 上发送用户令牌。POST /v1/realtime/sessions（使用用户令牌）会返回一个短期有效的 client_secret，它只能打开一次连接；详见实时语音。

控制台​

控制台使用你的谷歌账号，而不是密钥。你在控制台里创建项目、管理项目的密钥和终端用户，查看用量、流水、调用记录和审计日志。详见控制台指南。