获取接口调用凭证

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

接口说明

接口英文名 auth.getAccessToken

功能描述 获取接口调用凭证（Access Token）。该凭证是小游戏服务端调用 SUD OP SVR 后台接口的全局唯一凭证，用于身份验证与接口权限控制。

注意：本接口直接以标准 HTTPS 请求调用，不支持服务通信二次加密和签名。game_id、secret 等参数以明文 JSON Body 形式传递，响应为标准 JSON 明文，无需构造加密报文、签名请求头或处理响应解密。请求体中的 secret 属于高风险凭证，请务必仅在服务器端调用。

调用方式

HTTPS 调用

POST /v1/auth/token

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

请求参数 - Body

Content-Type 请使用 application/json。

属性	类型	默认值	必填	说明
grant_type	string		是	固定填写 client_credential
game_id	string		是	游戏唯一标识
secret	string		是	游戏密钥（GameSecret）
force_refresh	boolean	false	否	强制刷新模式开关。false: 普通模式，access_token 有效期内重复调用不会更新 access_token；true: 强制刷新模式，会导致上次获取的 access_token 失效，并返回新的 access_token

返回值

返回的 JSON 数据包

属性	类型	说明
errcode	int32	错误码
errmsg	string	错误信息
access_token	string	获取到的接口调用凭证
expires_in	int32	凭证有效时间，单位：秒。通常为 7200 秒（2 小时）

调用示例

cURL 请求

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

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

返回数据示例

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

最佳实践与凭证管理

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

1. 凭证刷新与管理架构

• access_token（动态凭证）：属于高频读取的短效凭证，必须且只能存入高性能分布式缓存（如 Redis）中，并利用 TTL 机制管理过期时间。
• 并发控制：在凭证过期触发续期时，多节点集群应使用分布式锁，确保同一时刻仅有一个节点向 SUD 服务端发起刷新请求，避免引发刷新风暴导致限流。
• 平滑刷新：为避免极端情况下网络抖动造成 token 失效，建议在 expires_in 到期前 5~10 分钟主动发起刷新。

时序逻辑参考：

2. 通用安全防范

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