菜单

API 模式接入

作者: 文耐下载

@rootauth/core 是不包含 UI 的 RootAuth SDK。业务方自行实现表单、loading、提示和页面跳转，SDK 负责请求、验证码、设备指纹、密码加密、MFA 和会话处理。

前置条件

在 RootAuth 工作台创建应用，并复制 app_id（格式如 app_******）。

请在项目根目录的 .npmrc 文件中添加下面这行配置：

bash 复制代码

@rootauth:registry=http://gitlab.standard-software.co/api/v4/projects/12421/packages/npm/

1. 安装

bash 复制代码

npm install @rootauth/core

2. 创建客户端

客户端保存 app_id、API 地址、OIDC 参数和语言等公共配置，后续认证方法都复用这份配置。

ts 复制代码

import { RootAuthClient, type RootAuthClientConfig } from '@rootauth/core'

const config: RootAuthClientConfig = {
  app_id: 'your-app-id',
  api_base_url: 'https://rootauth-api.rootauth.com',
  redirect_uri: window.location.origin,
  scope: ['openid'],
  cloudflare_container: '#rootauth-turnstile',
}

const rootAuth = new RootAuthClient(config)

// 可选：提前获取并缓存应用配置和设备指纹，减少首次登录或注册的等待时间。
await rootAuth.install()

install() 初始化失败时不会阻断页面启动；未调用或预取失败时，login() 和 register() 会在请求前自动补充获取。

2.1 RootAuthClientConfig配置参数

参数	类型	必填	默认值	说明
`app_id`	`string`	是	无	RootAuth 控制台创建应用后取得的应用 ID
`api_base_url`	`string`	否	`https://rootauth-api.rootauth.com`	API 地址
`redirect_uri`	`string`	否	`window.location.origin`	登录或注册成功后的回调地址
`scope`	`string[]`	否	`['openid']`	需要返回的用户字段
`state`	`string`	否	`undefined`	自定义状态，回调时原样返回
`grant_type`	`string`	否	`authorization_code`	授权模式
`locale`	`string`	否	`zh-CN`	支持 `zh-CN`、`en-US`
`enable_google_one_tap`	`boolean`	否	`false`	是否允许 `googleOneTapLogin()` 启动 Google One Tap
`cloudflare_container`	`string`	使用 Cloudflare 时是	`undefined`	所有 Turnstile 模式使用的专用容器 CSS selector，例如`#cloudflare_container`

3. 调用约定

认证方法统一返回 Promise，部分流程同时支持 onSuccess 回调。传入回调后，业务方接管成功结果；接口失败时则抛出标准化错误对象。

ts 复制代码

interface RootAuthFlowCallbacks<T> {
  onSuccess?: (response: T) => void
}

传入 onSuccess 后，登录和注册不会执行 SDK 默认跳转或自动登录逻辑，由业务方处理成功结果。

以下接口支持该回调约定：sendCode()、login()、verifyLoginMfa()、register()、resetPassword()、updateProfile()。

ts 复制代码

try {
  const response = await rootAuth.login(params, {
    onSuccess(result) {
      console.log(result.rootauth_message)
    },
  })
} catch (error) {
  console.error(error)
}

成功响应和错误对象可能带有 SDK 提示：

ts 复制代码

interface RootAuthMessage {
  type: string
  msg: string
}

interface RootAuthMessageCarrier {
  rootauth_message?: RootAuthMessage
}

type 取值为 success、warning 或 error，msg 是后端按当前语言返回的最终多语言文案。

Core 不显示任何 UI，业务方需要根据 rootauth_message 或错误对象自行展示提示。

4. 登录 `login()`

login() 支持邮箱、手机号、用户名、验证码、WhatsApp。

4.1 `type` 完整列表

`type`	登录方式	必填字段
`EMAIL_PASS`	邮箱 + 密码	`email`、`password`
`EMAIL_CODE`	邮箱 + 验证码	`email`、`code`
`PHONE_PASS`	手机号 + 密码	`phone_code`、`phone_num`、`password`
`PHONE_CODE`	手机号 + 短信验证码	`phone_code`、`phone_num`、`code`
`USER_NAME_PASS`	用户名 + 密码	`user_name`、`password`
`WHATSAPP_CODE`	WhatsApp 验证码	`phone_code`、`phone_num`、`code`

4.2 参数

参数	类型	必填条件	说明
`type`	`string`	始终必填	取值见上表
`email`	`string`	`EMAIL_PASS`、`EMAIL_CODE`	邮箱地址
`phone_code`	`string`	`PHONE_PASS`、`PHONE_CODE`、`WHATSAPP_CODE`	国际区号，不带 `+`，例如 `86`
`phone_num`	`string`	`PHONE_PASS`、`PHONE_CODE`、`WHATSAPP_CODE`	不带国际区号的手机号
`user_name`	`string`	`USER_NAME_PASS`	用户名
`password`	`string`	密码登录	传入明文，SDK 会按应用公钥加密
`code`	`string \| number`	验证码登录	6 位验证码
`is_invite`	`number`	`EMAIL_PASS`、`EMAIL_CODE`	是否通过邀请注册登录
`device_id`	`string`	可选	设备指纹；未传入时 SDK 自动生成
`redirect_uri`、`scope`、`state`、`grant_type`	同全局配置	否	单次请求覆盖全局配置，通常无需传入

ts 复制代码

const handleSubmit = () => {
  // 用户自行处理前置校验
  loading.value = true
  rootauth
    ?.login(
      {
        type: 'EMAIL_PASS',
        email: '123456@qq.com',
        password: '123456',
      },
      {
        onSuccess: res => {
          // 用户自己的登录成功回调，包括提示等
          if (res.rootauth_message.msg) {
            message[res.rootauth_message.type || 'success'](res.rootauth_message.msg)
          }
        },
      }
    )
    .catch(err => {
      // 统一在这里处理请求失败
      if (err.rootauth_message.msg) {
        message[err.rootauth_message.type || 'error'](err.rootauth_message.msg)
      }
    })
    .finally(() => {
      loading.value = false
    })
}

手机号密码登录：

ts 复制代码

await rootAuth.login({
  type: 'PHONE_PASS',
  phone_code: '86',
  phone_num: '13800138000',
  password: 'Password123',
})

5. 发送验证码 `sendCode()`

sendCode() 负责发送登录、注册、重置密码和 MFA 流程所需的验证码。

获取验证码时，如果出现“验证码错误次数过多，请重新获取”的错误提示，请到【工作台-通用安全-验证码规则-验证码尝试次数】查看次数是否符合需求。

5.1 `type` 完整列表

`type`	验证方式	必填字段
`EMAIL`	邮箱验证码	`email`、`email_template_type`
`PHONE_TEXT`	短信验证码	`phone_code`、`phone_num`、`phone_text_template_type`
`WHATSAPP`	WhatsApp 验证码	`phone_code`、`phone_num`

5.2 `email_template_type`、`phone_text_template_type` 模板类型列表

模板值	用途
`register_code`	注册验证码
`login_code`	登录验证码
`reset_pass_code`	重置密码验证码
`login_mfa_code`	MFA 登录验证码；同时传入 `mfa_token`

5.3 参数

参数	类型	必填条件	说明
`type`	`string`	必填	`EMAIL`、`PHONE_TEXT` 或 `WHATSAPP`
`email`	`string`	`EMAIL`	邮箱地址
`email_template_type`	`string`	`EMAIL`	邮件模板
`phone_code`	`string`	`PHONE_TEXT`、`WHATSAPP`	国际区号，不带 `+`，例如 `86`
`phone_num`	`string`	`PHONE_TEXT`、`WHATSAPP`	不带区号的完整手机号
`phone_text_template_type`	`string`	`PHONE_TEXT`	短信模板
`mfa_token`	`string`	模板为 `login_mfa_code`	登录接口返回的 MFA token
`ticket`	`string`	应用启用验证码且由业务传入时	腾讯验证码 ticket；SDK 自动流程会覆盖该值
`ticket_rand_str`	`string`	应用启用验证码且由业务传入时	腾讯验证码 ticket 对应的随机字符串
`device_id`	`string`	可选	设备指纹；未传入时 SDK 自动生成
`redirect_uri`、`scope`、`state`、`grant_type`	同全局配置	否	单次请求覆盖全局配置，通常无需传入

email_template_type 仅用于 EMAIL，phone_text_template_type 仅用于 PHONE_TEXT；WHATSAPP 不需要模板参数。

ts 复制代码

const params: SendCodeParams = {
  type: 'EMAIL',
  email: '123456@qq.com',
  email_template_type: 'register_code',
}

rootauth
  ?.sendCode(params)
  .then(res => {
    // 基于当前的RootAuth逻辑，补充自有逻辑
  })
  .catch(err => {
    console.error(err)
  })
  .finally(() => {})

ts 复制代码

await rootAuth.sendCode({
  type: 'PHONE_TEXT',
  phone_code: '86',
  phone_num: '13800138000',
  phone_text_template_type: 'login_code',
})

应用开启验证码时，SDK 会自动执行腾讯验证码流程。发送验证码有60秒限制，请用户自行添加倒计时提示。

6. 注册 `register()`

register() 支持邮箱、手机号、用户名和 WhatsApp 的注册方式。

6.1 `type` 完整列表

`type`	注册方式	必填字段
`EMAIL_CODE_PASS`	邮箱验证码 + 密码	`email`、`code`、`password`
`PHONE_CODE_PASS`	手机验证码 + 密码	`phone_code`、`phone_num`、`code`、`password`
`USER_NAME_PASS`	用户名 + 密码	`user_name`、`password`
`WHATSAPP_CODE`	WhatsApp 验证码注册	`phone_code`、`phone_num`、`code`

6.2 参数

参数	类型	必填条件	说明
`type`	`string`	始终必填	注册方式，取值见上表
`email`	`string`	`EMAIL_PASS`、`EMAIL_CODE`	邮箱地址
`phone_code`	`string`	`PHONE_CODE_PASS`、`PHONE_CODE`、`WHATSAPP_CODE`	国际区号，不带 `+`，例如 `86`
`phone_num`	`string`	`PHONE_CODE_PASS`、`PHONE_CODE`、`WHATSAPP_CODE`	不带区号的手机号
`user_name`	`string`	`USER_NAME_PASS`	用户名
`code`	`string \| number`	`EMAIL_CODE`、`PHONE_CODE`、`WHATSAPP_CODE`	验证码
`password`	`string`	`EMAIL_PASS`、`PHONE_CODE_PASS`、`USER_NAME_PASS`	明文密码，SDK 自动加密
`device_id`	`string`	可选	设备指纹；未传入时 SDK 自动生成
`redirect_uri`、`scope`、`state`、`grant_type`	同全局配置	否	单次请求覆盖全局配置，通常无需传入

ts 复制代码

await rootAuth.register({
  type: 'EMAIL_CODE_PASS',
  email: 'demo@example.com',
  code: '123456',
  password: 'Password123',
})

ts 复制代码

await rootAuth.register({
  type: 'USER_NAME_PASS',
  user_name: 'demo-user',
  password: 'Password123',
})

7. 重置密码 `resetPassword()`

重置密码支持直接提交验证码，也支持先校验验证码、再使用 verify_token 提交新密码。

7.1 校验验证码 `verifyResetPasswordCode()`

参数	类型	必填条件	说明
`type`	`string`	始终必填	`EMAIL_CODE` 或 `PHONE_CODE`
`email`	`string`	`EMAIL_CODE`	邮箱地址
`phone_code`	`string`	`PHONE_CODE`	国际区号，不带 `+`，例如 `86`
`phone_num`	`string`	`PHONE_CODE`	不带区号的手机号
`code`	`number`	始终必填	验证码

ts 复制代码

const verification = await rootAuth.verifyResetPasswordCode({
  type: 'EMAIL_CODE',
  email: 'demo@example.com',
  code: 123456,
})

返回数据包含 verify_token。

7.2 重置密码 `resetPassword()`

code 和 verify_token 至少传一个。

参数	类型	必填条件	说明
`type`	`string`	始终必填	`EMAIL_CODE` 或 `PHONE_CODE`
`email`	`string`	`EMAIL_CODE`	邮箱地址
`phone_code`	`string`	`PHONE_CODE`	国际区号，不带 `+`，例如 `86`
`phone_num`	`string`	`PHONE_CODE`	不带区号的手机号
`password`	`string`	始终必填	新密码
`password_confirmation`	`string`	始终必填	确认新密码
`code`	`string \| number`	未传 `verify_token` 时必填	验证码
`verify_token`	`string`	未传 `code` 时必填	验证码校验接口返回的 token
`redirect_uri`、`scope`、`state`、`grant_type`	同全局配置	否	单次请求覆盖全局配置

ts 复制代码

await rootAuth.resetPassword({
  type: 'EMAIL_CODE',
  email: 'demo@example.com',
  verify_token: verification.data.data.verify_token,
  password: 'NewPassword123',
  password_confirmation: 'NewPassword123',
})

8. MFA `verifyLoginMfa()`

verifyLoginMfa() 处理邮箱、手机号和 TOTP 二次认证，也支持首次绑定邮箱、手机号或验证器。

登录响应包含 mfa_token 时，根据 mfa_methods 展示对应验证方式。

`mfa_type`	含义	`code` 内容	额外字段
`EMAIL`	已绑定邮箱验证	邮箱验证码	无
`EMAIL_BIND`	绑定邮箱并验证	邮箱验证码	`email`
`PHONE_CODE`	已绑定手机号验证	短信验证码	通常使用登录响应中的手机号
`PHONE_CODE_BIND`	绑定手机号并验证	短信验证码	`phone_code`、`phone_num`
`TOTP`	已绑定验证器验证	验证器动态码	无
`TOTP_BIND`	首次绑定验证器	验证器动态码	选择验证码时传 `totp_bind_code`

8.1 参数

参数	类型	必填条件	说明
`mfa_token`	`string`	始终必填	登录响应返回的 MFA token
`mfa_type`	`string`	始终必填	取值见上表
`code`	`string \| number`	始终必填	邮箱、短信或 TOTP 验证码
`email`	`string`	`EMAIL_BIND`	待绑定邮箱
`phone_code`	`string`	`PHONE_CODE_BIND`	待绑定手机号的国际区号
`phone_num`	`string`	`PHONE_CODE_BIND`	待绑定的手机号
`totp_bind_code`	`string`	`TOTP_BIND` 且选择验证码	邮箱或手机号的验证码

ts 复制代码

await rootAuth.verifyLoginMfa({
  mfa_token: 'token-from-login',
  mfa_type: 'TOTP',
  code: '123456',
})

mfa_methods 可能包含多个可选方式。TOTP_BIND 时，登录响应还可能包含用于生成二维码的 totp_secret。

9. 第三方登录

第三方认证包括 Google OAuth、Telegram、Facebook、VK 和微信服务号二维码流程。

9.1 `thirdPartyLogin()`

参数	类型	必填条件	说明
`auth_by`	`string`	始终必填	`google_oauth`、`telegram`、`facebook` 或 `vkid`
`response_type`	`string`	可选	OAuth 响应类型
`device_id`	`string`	可选	设备指纹；未传入时 SDK 自动生成
`redirect_uri`、`scope`、`state`、`grant_type`	同全局配置	否	单次请求覆盖全局配置，通常无需传入

`auth_by`	登录方式
`google_oauth`	Google OAuth
`telegram`	Telegram
`facebook`	Facebook
`vkid`	VK ID

ts 复制代码

await rootAuth.thirdPartyLogin({
  auth_by: 'google_oauth',
})

该方法取得授权地址后会跳转redirect_uri配置的页面。

WhatsApp 不属于第三方 OAuth 登录，登录和注册均通过 login() 或 register() 接口，并使用 type: 'WHATSAPP_CODE'。

9.2 Google One Tap

ts 复制代码

const rootAuth = new RootAuthClient({
  app_id: 'your-app-id',
  enable_google_one_tap: true,
})

await rootAuth.googleOneTapLogin()

控制台应用和 Google Cloud 回调地址也必须正确配置。

9.3 微信服务号二维码

微信服务号调用 wechatServiceQrLogin() 获取二维码授权数据，再携带返回的 state_key 调用 getThirdPartyQrResult() 查询扫码结果。

ts 复制代码

const qr = await rootAuth.wechatServiceQrLogin()

const result = await rootAuth.getThirdPartyQrResult({
  state_key: qr.data.data.state_key,
})

业务方根据 qr.data.data.qr_url 或 authorize_url 展示二维码，并按 expire_seconds 控制轮询时长。getThirdPartyQrResult() 只执行一次查询，业务方需要自行轮询，并在成功、过期或页面销毁时停止。

10. 会话、配置和语言

本节汇总获取当前用户、退出登录、读取应用配置和切换语言等辅助接口。这些能力与登录注册流程共用同一个 Core 客户端。

ts 复制代码

await rootAuth.getAppConfig()
rootAuth.getToken()
rootAuth.isAuthenticated()
rootAuth.logout()
rootAuth.setAppId('another-app-id')
rootAuth.setLocale('en-US')

语言优先级为 URL 中的 lang、locale 或 language，其次是客户端 locale，最后为 zh-CN。

11. 相关模式

@rootauth/web-components：框架无关的登录、注册、重置密码和 MFA 表单
@rootauth/vue：Vue 3 hosted 完整认证页面
@rootauth/react：React 18+ hosted 完整认证页面

上一个

前端接入

下一个

Vue 模式接入

最近修改: 2026-08-28Powered by

大纲

API 模式接入

前置条件

1. 安装

2. 创建客户端

2.1 RootAuthClientConfig配置参数

3. 调用约定

4. 登录 login()

4.1 type 完整列表

4.2 参数

5. 发送验证码 sendCode()

5.1 type 完整列表

5.2 email_template_type、phone_text_template_type 模板类型列表

5.3 参数

6. 注册 register()

6.1 type 完整列表

6.2 参数

7. 重置密码 resetPassword()

7.1 校验验证码 verifyResetPasswordCode()

7.2 重置密码 resetPassword()

8. MFA verifyLoginMfa()

8.1 参数

9. 第三方登录

9.1 thirdPartyLogin()

9.2 Google One Tap

9.3 微信服务号二维码

10. 会话、配置和语言

11. 相关模式

4. 登录 `login()`

4.1 `type` 完整列表

5. 发送验证码 `sendCode()`

5.1 `type` 完整列表

5.2 `email_template_type`、`phone_text_template_type` 模板类型列表

6. 注册 `register()`

6.1 `type` 完整列表

7. 重置密码 `resetPassword()`

7.1 校验验证码 `verifyResetPasswordCode()`

7.2 重置密码 `resetPassword()`

8. MFA `verifyLoginMfa()`

9.1 `thirdPartyLogin()`