获取接口调用凭证
本接口应在服务器端调用,严禁在前端(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_type | string | 是 | 固定填写 client_credential | |
| app_id | string | 是 | 应用唯一标识 AppId | |
| secret | string | 是 | 应用密钥(AppSecret) | |
| force_refresh | boolean | false | 否 | 强制刷新模式开关。false:普通模式,凭证有效期内重复调用不会签发新凭证,返回当前凭证及其剩余有效期;true:强制刷新模式,立即签发新凭证,旧凭证在 5 分钟内仍然有效,5 分钟后失效(便于多节点缓存更新过渡)。每天限用 20 次,两次调用间隔需 ≥ 30 秒 |
返回值
返回的 JSON 数据包
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 错误码 |
| errmsg | string | 错误信息 |
| access_token | string | 获取到的全局唯一接口调用凭据 |
| expires_in | number | 凭证有效时间,单位:秒。普通模式下为当前凭证的剩余有效时长;强制刷新模式下为新签发凭证的完整有效期,通常为 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 获取请求。
