跳到正文
联系我们 开始接入
认证 API

认证 API 总览

接入 iKho Embedded 需要两级令牌:应用级的合作方令牌用于签发用户令牌,用户级的用户令牌用于绑定设备与上传文件。

开发者平台处于内测阶段,接口契约以联调时提供的正式文档为准。当前 base URL 为 https://ikho.cn/developer/api,凭证由对接工程师开通,见联系我们。

两级令牌

合作方令牌代表你的应用,用来为每一位终端用户签发用户令牌;用户令牌代表单个用户,交给 Embedded SDK 与文件上传接口使用。两级令牌各有有效期与鉴权方式。

令牌级别有效期鉴权方式用途
合作方令牌 partner token应用级约 2 小时Basic base64(client_id:secret)签发用户令牌;通过 refresh_token 刷新自身
用户令牌 user token用户级约 24 小时Bearer 合作方令牌换取绑定 S1 录音卡、上传音频文件

获取流程

1
换取合作方令牌
用对接工程师提供的 client_id 与 secret,通过 Basic 鉴权调用 POST /oauth/partner/access-token。
2
为用户签发用户令牌
用合作方令牌作为 Bearer 凭证,为你系统里的每位用户调用 POST /open/partner/users/access-token。
3
到期前刷新
合作方令牌到期前,用签发时返回的 refresh_token 调用 POST /oauth/partner/refresh-token 续期。

令牌安全最佳实践

  • secret 只留在你的后端。client_id 与 secret 是应用级凭证,只能存放在你的服务端,绝不能打进移动应用、网页前端或任何可被反编译的分发包。合作方令牌的换取与刷新都应由你的后端完成。
  • 客户端只持有短时效的用户令牌。用户令牌按用户逐一签发、有效期短,即使泄露,影响范围也限定在单个用户。客户端应在需要时向你自己的后端请求,由后端代为签发,不要在客户端缓存长期凭证。
  • 怀疑泄露立即轮换。如果 secret 或令牌存在泄露风险,请联系对接工程师重置凭证;重置后旧凭证随即失效,用新凭证重新换取令牌即可恢复。

错误结构与错误码见错误码参考。