菜单

服务端接入

下载

服务端 API 接入用于让应用后端使用 client_credentials 获取访问令牌，并调用应用集成配置、用户注册和 MFA 相关接口。

Server 类接口只能使用 client_credentials 授权的 access_token，不能使用用户态 access_token。

 

1. 开始前准备

  1. 登录 RootAuth 工作台，进入目标应用。
  2. 打开「配置」→「应用管理」→「协议配置」，开启 client_credentials 授权模式。
  3. 在协议配置中添加调用服务端 API 的服务器 IP 白名单。
  4. 获取当前应用的 app_id 和 app_secret。

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

 

2. 请求约定

2.1 请求域名

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

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

 

2.2 通用 Header

除获取 Token 接口外，请在请求头中传入：

字段 是否必传 类型 说明
X-ROOT-AUTH-APP-ID 是 string 当前应用的 app_id。
X-ROOT-AUTH-TOKEN 是 string 通过 client_credentials 获取的服务端 access_token。
X-ROOT-AUTH-LANG 否 string 语言。支持中文 zh-CN 和英文 en-US。注册语言及验证码内容会使用该值。

 

3. 获取服务端 Token

使用 client_credentials 换取服务端 access_token。该 Token 只能从 IP 白名单中的服务器使用。

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

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

 

3.1 Body 参数

字段 是否必传 类型 说明
nonce 是 string 32 位随机字符串，每次请求必须不同。
timestamp 是 int 秒级时间戳，允许 5 分钟内误差。
sign 是 string md5(app_secret + nonce + timestamp)。
grant_type 是 string 固定传入 client_credentials，使用此模式必须配置IP白名单。

 

3.2 签名示例

nonce = 73ec4021ae77fc43156b583d7806b4eb
timestamp = 1772280549
app_secret = abc123

sign 原文：abc12373ec4021ae77fc43156b583d7806b4eb1772280549
sign：a2faee2c487060ca51e9287d52b06a71

 

3.3 请求示例

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": "client_credentials"
  }'

 

3.4 响应字段

字段 类型 说明
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 Token 过期时间戳，可在工作台修改有效时长。 
{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "access_token": "eyJ...",
    "access_token_expire_at": 1770129221
  }
}

 

4. 获取应用集成配置

获取当前应用 ID 和密码传输 RSA 公钥。公钥不定期更新，建议动态获取。

请求路径：/server/v1/application/get_application_integration_config

 

4.1 请求示例

curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application/get_application_integration_config' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{}'

 

4.2 响应字段

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

 

5. 服务端创建用户

使用服务端 Token 创建邮箱密码用户。

请求路径：/server/v1/application_user/register

 

5.1 Body 参数

字段 是否必传 类型 说明
type 是 string 当前支持 SERVER_EMAIL_PASS，表示邮箱密码注册。
email 是 string 用户邮箱。
password 是 string

类型SERVER_EMAIL_PASS必填，8-20 位，必须包含大写字母、小写字母和数字。使用最新 RSA 公钥按 RSA-PKCS1 加密后，再以 Base64 字符串传入。

 

5.2 请求示例

curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/register' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --header 'X-ROOT-AUTH-LANG: zh-CN' \
  --data-raw '{
    "type": "SERVER_EMAIL_PASS",
    "email": "user@example.com",
    "password": "RSA_PKCS1_BASE64_PASSWORD"
  }'

 

5.3 响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data struct 返回内容，data 为空时返回 null。
data.user_str_id string 应用用户 ID。 
{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "user_str_id": "user_904fb9e691ba8117ffbb6cd5b918611c"
  }
}

 

6. 服务端完成 MFA

服务端 MFA 通常按照「开始 MFA → 按需发送验证码 → 提交验证」执行。需要解除已绑定的 OTP 时，再调用解绑接口。

 

6.1 开始 MFA

请求路径：/server/v1/application_user/mfa_start

Body 字段 是否必传 类型 说明
user_str_id 是 string 要验证的应用用户 ID。 
curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/mfa_start' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{"user_str_id":"user_******"}'

响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data struct 返回内容，data 为空时返回 null。
data.mfa_token string 本次 MFA Token，默认 10 分钟过期。
data.mfa_methods string[] 当前用户可用的 MFA 方式。
totp_bind_secret string 仅 TOTP_BIND 可用时值存在，绑定密钥。
totp_bind_need_verify_code bool 仅 TOTP_BIND 可用时值存在，表示绑定是否需要验证码。
user_name string 仅 TOTP_BIND 可用时值存在，用户名。
email_mask string 脱敏后的邮箱。
phone_code string 手机区号。
phone_num_mask string 脱敏后的手机号码。

 

其中mfa_methods 可能包含：

值 说明
EMAIL 使用已绑定邮箱验证码。
EMAIL_BIND 绑定邮箱并验证。
TOTP 使用已绑定验证器的一次性验证码。
TOTP_BIND 首次绑定验证器。
PHONE_CODE 使用已绑定手机号验证码。
PHONE_CODE_BIND 绑定手机号并验证。
PASSWORD 使用密码验证。 
{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "mfa_token": "a6a68826db6376417830cff6c4a336df",
    "mfa_methods": ["EMAIL", "TOTP_BIND", "PHONE_CODE_BIND"],
    "totp_bind_secret": "ARFNO6BVTVTBQ63SP2IOR6WDURZPX35K",
    "email_mask": "t***@qq.com"
  }
}

 

6.2 发送 MFA 验证码

请求路径：/server/v1/application_user/get_verify_code

Body 字段 是否必传 类型 说明
type 是 string EMAIL 或 PHONE_TEXT。
email EMAIL 可传 string 邮箱地址。
email_template_type EMAIL 必传 string MFA 场景传入 login_mfa_code。
phone_code PHONE_TEXT 必传 string 区号，例如 86。
phone_num PHONE_TEXT 可传 string 不含区号的手机号。
phone_text_template_type PHONE_TEXT 必传 string MFA 场景传入 login_mfa_code。
mfa_token login_mfa_code 模板必填 string 开始 MFA 接口返回的 Token。过期后不能继续获取验证码。 
curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/get_verify_code' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{
    "type": "EMAIL",
    "email_template_type": "login_mfa_code",
    "mfa_token": "a6a68826db6376417830cff6c4a336df"
  }'

响应字段

字段 类型 说明
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
}

 

6.3 验证 MFA

请求路径：/server/v1/application_user/mfa_verify

Body 字段 是否必传 类型 说明
mfa_type 是 string 从开始 MFA 接口返回的可用方式中选择。
mfa_token 是 string 本次 MFA Token。
code 非 PASSWORD 必传 string 邮箱、短信或 TOTP 验证码。
password PASSWORD 必传 string 使用最新 RSA 公钥按 RSA-PKCS1 加密并 Base64 编码后的密码。
email EMAIL_BIND 必传 string 需要绑定的邮箱。
phone_code PHONE_CODE_BIND 必传 string 手机号区号。
phone_num PHONE_CODE_BIND 必传 string 不含区号的手机号。
totp_bind_code 否 string 仅在绑定 TOTP 且用户已有手机或邮箱时，传入对应验证码。 
curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/mfa_verify' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{
    "mfa_type": "EMAIL",
    "mfa_token": "a6a68826db6376417830cff6c4a336df",
    "code": "123456"
  }'

响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data struct 返回内容，data 为空时返回 null。
data.verified bool 校验结果。
data.verified_at int 校验时间。
data.user_str_id string 校验用户 ID。 
{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "verified": true,
    "verified_at": 1781166828,
    "user_str_id": "user_4aa0f411487ff944cf5af73fce5d8883"
  }
}

 

6.4 解绑 MFA

当前接口用于解绑 TOTP 验证器。

请求路径：/server/v1/application_user/mfa_unbind

Body 字段 是否必传 类型 说明
mfa_type 是 string 传入 TOTP。
user_str_id 是 string 用户 ID。 
curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/mfa_unbind' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{
    "mfa_type": "TOTP",
    "user_str_id": "user_******"
  }'

响应字段

字段 类型 说明
status_code int 返回码，正常为 200，其他均为失败。
error_code int 业务返回码，正常为 0，其他均为失败。
error_msg string 业务返回信息。
data struct 返回内容，data 为空时返回 null。
data.unbound bool 解绑结果。
data.unbound_at int 解绑时间。
data.user_str_id string 解绑用户 ID。 
{
  "status_code": 200,
  "error_code": 0,
  "error_msg": "success",
  "data": {
    "unbound": true,
    "unbound_at": 1781173918,
    "user_str_id": "user_4aa0f411487ff944cf5af73fce5d8883"
  }
}

 

7. 服务端修改用户资料

使用服务端 Token 修改指定用户的资料，当前支持修改密码和修改用户名。

请求路径：/server/v1/application_user/update_profile

 

7.1 Body 参数

字段 是否必传 类型 说明
user_str_id 是 string 要修改的应用用户 ID。
password 否 string 新密码。传入则修改密码，格式需符合应用密码格式配置。使用最新 RSA 公钥按 RSA-PKCS1 加密后，再以 Base64 字符串传入。
password_old 条件必传 string 旧密码。当应用开启「修改密码需校验旧密码」且用户已设置密码时必传；用户无密码时免校验。同样使用最新 RSA 公钥按 RSA-PKCS1 加密后 Base64 传入。
user_name 否 string 新用户名。传入则修改用户名，需符合应用用户名格式配置；留空表示不修改，且不支持清空为空。

 

7.2 请求示例

curl --request POST \
  'https://rootauth-api.rootauth.com/server/v1/application_user/update_profile' \
  --header 'Content-Type: application/json' \
  --header 'X-ROOT-AUTH-APP-ID: app_******' \
  --header 'X-ROOT-AUTH-TOKEN: eyJ...' \
  --data-raw '{
    "user_str_id": "user_******",
    "password": "RSA_PKCS1_BASE64_NEW_PASSWORD",
    "password_old": "RSA_PKCS1_BASE64_OLD_PASSWORD",
    "user_name": "new_user_name"
  }'

 

7.3 响应字段

字段 类型 说明
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
}
上一个
OAuth授权码接入
下一个
用户态API接入
最近修改: 2026-07-16Powered by