用户态API接入

用户态 API 供应用后端代表当前用户修改资料、修改密码或解绑第三方账号。

Auth 类接口只能使用通过 authorization_code 兑换的用户态 access_token。

 

1. 开始前准备

1. 登录 RootAuth 工作台，进入「配置」→「应用管理」→「协议配置」，开启 authorization_code 授权模式。
2. 获取应用的 app_id 和 app_secret。app_secret 不能对外暴露，仅在服务端访问时使用。
3. 调用 Token 接口，使用 authorization_code 兑换用户态 access_token。
4. 调用“获取应用配置”或“获取应用集成配置”接口获取 RSA 公钥。公钥不定期更新，建议动态获取。

如尚未获取用户态 Token，请先参考「OAuth 授权码接入」文档。

 

2. 请求约定

2.1 请求地址

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

本文接口均使用 POST 方法，请求体格式为 application/json。

 

2.2 公共请求头

请求头	必填	类型	说明
X-ROOT-AUTH-APP-ID	是	string	RootAuth 应用的 App ID
X-ROOT-AUTH-TOKEN	是	string	通过 OAuth 授权码流程获取的用户 Access Token
X-ROOT-AUTH-LANG	否	string	语言，可选 zh-CN 或 en-US。用户注册语言、验证码邮件内容等以此为准

 

3. 获取应用配置

修改密码前，需要获取应用当前使用的 RSA 公钥。公钥不定期更新，建议动态获取。

3.1 方法与路径

POST /auth/v1/application/get_application_setting

此接口不需要传入 X-ROOT-AUTH-TOKEN。

 

3.2 请求示例

curl -X POST 'https://rootauth-api.rootauth.com/auth/v1/application/get_application_setting' \
  -H 'Content-Type: application/json' \
  -H 'X-ROOT-AUTH-APP-ID: your_app_id' \
  -d '{}'

 

3.3 响应字段

字段	类型	说明
status_code	int	返回码，正常为 200，其他均为失败
error_code	int	业务返回码，正常为 0，其他均为失败
error_msg	string	业务返回信息
data	struct	返回内容，data 为空时返回 null
data.pass_trans_rsa_public_key	string	应用 RSA 密码加密公钥

{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "pass_trans_rsa_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8"
  }
}

 

4. 更新用户资料

使用此接口修改当前用户的用户名或密码。

4.1 方法与路径

POST /auth/v1/application_user/update_profile

 

4.2 请求参数

参数	类型	必填	说明
user_name	String	否	用户名，支持字母、数字、下划线和连字符，长度为 4–52 个字符，不区分大小写，需符合工作台应用配置的规则。
password	String	否	新密码。使用应用 RSA 公钥按 PKCS#1 加密，再进行 Base64 编码
password_old	String	传入 password 时必填	原密码

密码长度为 8–20 个字符，且必须同时包含大写字母、小写字母和数字。

 

4.3 密码加密步骤

1. 调用应用配置接口获取 pass_trans_rsa_public_key。
2. 使用 RSA PKCS#1 对明文密码进行加密。
3. 对加密结果进行 Base64 编码。
4. 将编码后的结果作为 password 提交。

 

4.4 请求示例

curl -X POST 'https://rootauth-api.rootauth.com/auth/v1/application_user/update_profile' \
  -H 'Content-Type: application/json' \
  -H 'X-ROOT-AUTH-APP-ID: your_app_id' \
  -H 'X-ROOT-AUTH-TOKEN: user_access_token' \
  -d '{
    "user_name": "rootauth_user"
  }'

密码重置之前签发的Token均会失效。

 

4.5 响应字段

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

{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": null
}

 

5. 解绑第三方账号

使用此接口解除当前 RootAuth 用户与指定第三方账号的绑定关系。

5.1 方法与路径

POST /auth/v1/third_login/unbind

 

5.2 请求参数

参数	类型	必填	说明
auth_by	String	是	第三方认证方式，可选 telegram 或 wechat_service等方式。
identity_id	String	否	第三方身份 ID。同一认证方式绑定多个账号时用于指定解绑对象。

 

5.3 请求示例

curl -X POST 'https://rootauth-api.rootauth.com/auth/v1/third_login/unbind' \
  -H 'Content-Type: application/json' \
  -H 'X-ROOT-AUTH-APP-ID: your_app_id' \
  -H 'X-ROOT-AUTH-TOKEN: user_access_token' \
  -d '{
    "auth_by": "wechat_service",
    "identity_id": "third_party_identity_id"
  }'

如果第三方登录是用户唯一的登录方式，则不允许解绑。

 

5.4 响应字段

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

{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": null
}