Skip to content

获取接口调用凭证 ​

本接口应在服务器端调用,严禁在前端(APP 客户端、网页、小游戏等)直接调用,避免凭证泄露风险。

接口说明 ​

接口英文名 auth.getAccessToken

功能描述 获取接口调用凭据(Access Token)。该凭据是 APP 服务端调用 SUD OP SVR 后台接口的全局唯一凭证,用于身份验证与接口权限控制。不支持第三方平台代调用。

注意:本接口直接以标准 HTTPS 请求调用,不支持请求加密签名。app_id、secret 等参数以明文 JSON Body 形式传递,响应为标准 JSON 明文,无需构造加密报文、签名请求头或处理响应解密。

调用方式 ​

HTTPS 调用 ​

http
POST /v1/auth/token

调用时,请在接口路径前拼接应用所属服务区域的基础地址,详见服务区域与接口地址。

请求参数 - Body ​

Content-Type 请使用 application/json。

属性类型默认值必填说明
grant_typestring是固定填写 client_credential
app_idstring是应用唯一标识 AppId
secretstring是应用密钥(AppSecret)
force_refreshbooleanfalse否强制刷新模式开关。false:普通模式,凭证有效期内重复调用不会签发新凭证,返回当前凭证及其剩余有效期;true:强制刷新模式,立即签发新凭证,旧凭证在 5 分钟内仍然有效,5 分钟后失效(便于多节点缓存更新过渡)。每天限用 20 次,两次调用间隔需 ≥ 30 秒

返回值 ​

返回的 JSON 数据包

属性类型说明
errcodeint32错误码
errmsgstring错误信息
access_tokenstring获取到的全局唯一接口调用凭据
expires_innumber凭证有效时间,单位:秒。普通模式下为当前凭证的剩余有效时长;强制刷新模式下为新签发凭证的完整有效期,通常为 7200 秒(2 小时)

调用示例 ​

说明:本接口为明文调用,以下请求示例与返回示例均为实际收发的报文原文,无需加密或签名。

cURL 请求 ​

bash
# 中国大陆示例;其他区域请使用对应的基础地址。
BASE_URL='https://cn-papi.sudbiz.cloud'

curl -X POST \
  "${BASE_URL}/v1/auth/token" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "grant_type": "client_credential",
  "app_id": "YOUR_APP_ID",
  "secret": "YOUR_APP_SECRET",
  "force_refresh": false
}'

返回数据示例 ​

json
{
  "errcode": 0,
  "errmsg": "ok",
  "access_token": "ACCESS_TOKEN",
  "expires_in": 7200
}

最佳实践与凭证管理 ​

为了保障接口调用的稳定性与系统的安全性,强烈建议开发者遵循以下规范进行 access_token 的获取与维护。

1. 凭证刷新与管理架构 ​

  • access_token(动态凭证):属于高频读取的短效凭证,必须且只能存入高性能分布式缓存(如 Redis)中,并利用 TTL 机制管理过期时间。
  • 并发控制:在凭证过期触发续期时,多节点集群应使用分布式锁,确保同一时刻仅有一个节点向 SUD 服务端发起刷新请求,避免引发刷新风暴导致限流。
  • 模式选择:缓存中没有有效凭证时,用普通模式(force_refresh: false)获取,接口会返回当前仍有效的凭证及其剩余有效期;进入提前刷新窗口时,必须用强制刷新模式(force_refresh: true)签发新凭证。
  • 平滑刷新:以普通模式返回的 expires_in(剩余时长)为准,当剩余时长降至 10 分钟以内时,立即以 force_refresh: true 发起刷新。强制刷新后旧凭证仍有 5 分钟有效期,足以覆盖各节点缓存尚未更新的过渡期;不要等到剩余 5 分钟以内才刷新,否则网络抖动时可能无凭证可用。
  • 刷新频次:受 force_refresh 限制(每天 20 次、两次调用间隔 ≥ 30 秒)约束,按 7200 秒有效期计算例行刷新每天约 12 次,需为异常重试预留余量;不要让每个业务节点各自发起强制刷新。

注意:两种模式下 expires_in 的语义不同。普通模式返回的是剩余有效时长,不可用完整有效期覆盖缓存 TTL,否则会把即将过期的凭证当成新凭证继续使用;强制刷新模式返回的是新凭证的完整有效期,缓存 TTL 应直接使用该值。

时序逻辑参考:

刷新失败(网络抖动、5xx、触发频次限制)时,旧凭证在 5 分钟宽限期内仍然可用,可在该窗口内重试;超过 5 分钟仍未刷新成功,后续接口调用会因凭证失效而失败,需触发告警。

2. 通用安全防范 ​

  • AppSecret 隔离保管:属于长期敏感静态密钥,需存储在 APP 服务端安全存储介质(如配置中心 Nacos/Apollo、密钥管理服务 KMS),严禁硬编码在代码、配置文件或前端应用中。
  • 白名单限制:建议在 SUD 管理后台配置服务器 IP 白名单,从源头阻断非法来源的 Token 获取请求。