菜单

OAuth授权码接入

下载

OAuth 授权码接入用于在用户通过 RootAuth 完成登录后，由应用服务端使用回调中的授权码兑换 Token。应用可以使用 access_token 调用用户态接口，使用 refresh_token 刷新 Token，或在本地验证 jwt_token。

 

1. 开始前准备

  1. 登录 RootAuth 工作台，进入目标应用。
  2. 在「配置」→「应用管理」→「应用配置」中配置登录回调地址。
  3. 获取当前应用的 app_id 和 app_secret。

安全提示：app_secret 不能对外暴露，仅在服务端访问时使用。

 

2. 请求约定

API 域名: https://rootauth-api.rootauth.com

本文接口均使用 POST 请求，请求体格式为 application/json，响应格式为 JSON。

 

3. 完成授权码登录

3.1 接收登录回调

用户通过 RootAuth 完成登录后，浏览器会跳转到应用配置的回调地址。例如：

https://example.com/callback?code=oauth_******&state=******

回调中的 code 用于调用 Token 接口。

 

3.2 生成请求签名

Token 接口需要使用以下规则生成签名：

sign = md5(app_secret + nonce + timestamp)
字段 说明
nonce 32 位随机字符串，每次请求必须不同。
timestamp 秒级时间戳，与 RootAuth 服务器时间误差不能超过 5 分钟。

示例：

nonce = 73ec4021ae77fc43156b583d7806b4eb
timestamp = 1772280549
app_secret = abc123

待签名原文：abc12373ec4021ae77fc43156b583d7806b4eb1772280549
sign：a2faee2c487060ca51e9287d52b06a71

 

3.3 使用授权码兑换 Token

请求方法：POST

请求路径：/auth/v1/application_user/token

Header 参数

字段 是否必传 类型 说明
X-ROOT-AUTH-APP-ID 是 string 当前应用的 app_id。

Body 参数

字段 是否必传 类型 说明
nonce 是 string 32 位且不可重复的随机字符串。
timestamp 是 int 秒级时间戳，允许 5 分钟内误差。
sign 是 string md5(app_secret + nonce + timestamp)。
grant_type 是 string 固定传入 authorization_code。
authorization_code 是 string RootAuth 登录回调下发的 code。

请求示例（帮助中心补充）

curl --request POST \
  'https://rootauth-api.rootauth.com/auth/v1/application_user/token' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --data-raw '{
    "nonce": "73ec4021ae77fc43156b583d7806b4eb",
    "timestamp": 1772280549,
    "sign": "a2faee2c487060ca51e9287d52b06a71",
    "grant_type": "authorization_code",
    "authorization_code": "oauth_******"
  }'

响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data struct 返回内容，data 为空时返回 null。
data.access_token string 用户态访问令牌。可用于调用用户资源接口，可主动禁用，不建议暴露给不受信任的客户端。
data.access_token_expire_at int access_token 过期时间，秒级时间戳。
data.refresh_token string 刷新令牌。每个值只能成功使用一次，也可在工作台或接口中主动禁用。
data.refresh_token_expire_at int refresh_token 过期时间，秒级时间戳。
data.jwt_token string 可在应用服务端本地验证并读取用户身份信息的 JWT。
data.jwt_token_expire_at int jwt_token 过期时间，秒级时间戳。

 

响应示例

{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "access_token": "eyJ...",
    "access_token_expire_at": 1770129221,
    "refresh_token": "eyJ...",
    "refresh_token_expire_at": 1772714021,
    "jwt_token": "eyJ...",
    "jwt_token_expire_at": 1770129221
  }
}

 

4. 使用 refresh_token 获取新 Token

Token 接口支持 refresh_token 授权模式。调用时将 grant_type 设为 refresh_token，并传入 refresh_token。

curl --request POST \
  'https://rootauth-api.rootauth.com/auth/v1/application_user/token' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --data-raw '{
    "nonce": "新的32位随机字符串",
    "timestamp": 1772280549,
    "sign": "按相同规则生成的签名",
    "grant_type": "refresh_token",
    "refresh_token": "eyJ..."
  }'

refresh_token 仅一次使用有效。

 

5. 验证 JWT Token

JWT 的签名算法取决于「协议配置」中的 JWT 签名算法设置。

算法 验证方式
HS256 RootAuth 使用当前应用的 app_secret 签名。应用服务端使用相同的 app_secret 验证。
RS256 RootAuth 使用应用私钥签名。应用服务端使用工作台中对应的公钥验证。

 

6. 禁用 Token

此接口用于主动禁用 access_token 或 refresh_token。

请求方法：POST

请求路径：/auth/v1/application_user/token_delete

 

6.1 Header 参数

字段 是否必传 类型 说明
X-ROOT-AUTH-APP-ID 是 string 当前应用的 app_id。

 

6.2 Body 参数

字段 是否必传 类型 说明
nonce 是 string 32 位且不可重复的随机字符串。
timestamp 是 int 秒级时间戳，允许 5 分钟内误差。
sign 是 string md5(app_secret + nonce + timestamp)。
token 是 string 要禁用的 Token。
token_type 是 string ACCESS_TOKEN 或 REFRESH_TOKEN。

 

6.3 请求示例

curl --request POST \
  'https://rootauth-api.rootauth.com/auth/v1/application_user/token_delete' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --data-raw '{
    "nonce": "新的32位随机字符串",
    "timestamp": 1772280549,
    "sign": "按签名规则生成的签名",
    "token": "eyJ...",
    "token_type": "ACCESS_TOKEN"
  }'

 

6.4 响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data null 返回内容，data 为空时返回 null。

 

6.5 响应示例

{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": null
}
最近修改: 2026-07-02Powered by