菜单

API 模式接入

RootAuth API 模式为您提供封装好的前端 API 接口，不包含任何 UI。您可以根据自己的设计风格自由实现登录、注册等页面，并调用 SDK 完成认证逻辑。

1. 准备工作

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

2.前置条件

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

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

3. 安装 SDK

在项目根目录执行以下命令安装依赖包：

4. 创建 RootAuthClient 实例

在入口文件（如 main.js）中创建实例：

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

const options: RootAuthClientConfig = {
    app_id: 'app_******', // 必填项，值为工作台创建应用生成的app_id
  }
  const client = new RootAuthClient(options)

4.1 完整配置项

（RootAuthClientConfig）

 interface RootAuthClientConfig {
  app_id: string // 必填项，从工作台应用配置获取
  api_base_url?: string // 请求后端api接口的路径，默认为https://rootauth-api.rootauth.com
  redirect_uri?: string // 登录成功后跳转的路径，默认为根路径location.origin
  state?: string // 自定义参数，原样在接口返回
  locale?: string // 传入当前语言，默认为zh-CN，当前支持zh-CN、en-US
  scope?: string[]  // scope映射关系，默认为['openid']，在此添加需要返回的头像、用户名等字段
  grant_type?: string // 授权模式，默认为authorization_code
  enable_google_one_tap?: boolean // 是否开启Google Onetap登陆，默认为false
}

注意：mode 参数已在该版本废弃，无需传递。

5. 注入全局实例

（以 Nuxt 为例）

其他框架（Vue、React 等）可参考类似思路，将 client 挂载到全局。

5.1 创建插件文件

plugins/rootauth.client.ts：

// plugins/rootauth.client.ts
import { RootAuthClient, type RootAuthClientConfig } from '@rootauth/core'
export default defineNuxtPlugin(() => {
  const options: RootAuthClientConfig = {
    app_id: 'app_******', // 必填项，值为工作台创建应用生成的app_id
  }
  const client = new RootAuthClient(options)

  return {
    provide: {
      rootauth: client,
    },
  }
})

5.2 注册插件

nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    '@/plugins/rootauth.client.ts',
  ]
})

5.3 在组件中获取实例

const { $rootauth } = useNuxtApp()
$rootauth?.xxx()

5.4 封装 Composable（推荐）

composables/useRootAuth.ts：

// composables/useRootAuth.ts
import type { RootAuthClient } from '@rootauth/core'

/** RootAuth 客户端（由 `plugins/rootauth.client` 在配置了 `ROOTAUTH_APP_ID` 时注入） */
export function useRootAuth(): RootAuthClient | undefined {
  return useNuxtApp().$rootauth as RootAuthClient | undefined
}

使用时：

const rootauth = useRootAuth()
rootauth?.xxx()

6. 通用注意事项

表单校验：RootAuth 不做前端校验，请在调用 API 前自行校验。
密码加密：只需传入明文密码，SDK 会自动加密。
回调覆盖：每个方法的第二个参数 callbacks 可以传入 onSuccess，会完全覆盖 SDK 默认行为。如果只需要补充额外逻辑（如关闭 loading），请直接使用 Promise 链（.then() / .catch()），不要传入第二个参数。
请求成功/失败：请求失败统一使用 Promise 的reject。请求成功/失败的返回结果均包含 rootauth_message 对象（包含 type 和 msg），已做国际化处理（中英文）。API 模式不会自动弹出任何 UI 提示，请自行处理报错展示。

7. API 方法详解

7.1 登录

当工作台选择【登录注册合并】时也使用此接口。

const rootauth = useRootAuth()

interface LoginParams {
  type: string // 必填项，登陆方式：EMAIL_PASS|EMAIL_CODE|PHONE_PASS|PHONE_CODE，现在支持账号密码登陆EMAIL_PASS、邮箱验证码登陆EMAIL_CODE、手机号密码登陆PHONE_CODE、手机验证码登陆PHONE_PASS
  email: string // 必填项，用户邮箱
  password?: string // 当type为EMAIL_PASS/PHONE_PASS必填，注意：仅需要传入明文密码，RootAuth进行加密处理
  code?: string // 当type为EMAIL_CODE/PHONE_CODE必填
    
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
}
// login方法的第二个参数
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// 请求成功/失败返回该文案给用户展示
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

//可使用的类型
rootauth?.login(
  params: LoginParams,
  callbacks?: RootAuthFlowCallbacks<RootAuthClientSuccessResponse<CustomerLoginResponse>>,
)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  // 统一在这里处理请求失败
  console.log('err', err)
})
.finally(() => {
  // 关闭loading等
})

覆盖默认行为的示例（传入第二个参数）：

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
  })
}

7.2 注册

interface RegisterParams {
  type?: string // 用户注册类型：EMAIL_CODE_PASS|PHONE_CODE_PASS，默认为邮箱验证码注册EMAIL_CODE_PASS，支持邮箱验证码注册EMAIL_CODE_PASS、手机验证码注册PHONE_CODE_PASS
  email?: string // 用户邮箱，type=EMAIL_CODE_PASS时必填，
  code: string // 必填项，邮箱/手机号激活码
  password: string // 必填项，密码，注意：仅需要传入明文密码，RootAuth进行加密处理
  phone_code?: string // 手机号区号，type=PHONE_CODE_PASS必填，示例：86
  phone_num?: string // 手机号，type=PHONE_CODE_PASS必填
    
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
}
// 与login方法的第二个参数相同
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// 请求成功/失败返回该文案给用户展示，与login相同
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

const params: RegisterParams = {
  email: '123456@qq.com',
  password: '123456',
  code: '123456',
}
  
rootauth?.register(params)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

7.3 发送验证码

interface SendCodeParams {
  type?: string // 发送验证码类型：EMAIL|PHONE_TEXT，默认为邮箱验证码EMAIL，支持邮箱验证码EMAIL、PHONE_TEXT短信验证码
  email?: string // 用户邮箱，type=EMAIL时必填
  email_template_type?: string // 选择的模板类型，type=EMAIL时必填，register_code|login_code|reset_pass_code，register_code|login_mfa_code：注册验证码，login_code：登录验证码，reset_pass_code：重置验证码，login_mfa_code：MFA登录验证码
  phone_code?: string // 手机号区号，type=PHONE_TEXT时必填，示例：86
  phone_num?: string // 手机号，type=PHONE_TEXT时必填
  phone_text_template_type?: string // 短信模板，type=PHONE_TEXT时必填，register_code|login_code|reset_pass_code|login_mfa_code，支持注册模板register_code、登陆模板login_code、重置密码模板reset_pass_code、MFA登陆模板login_mfa_code
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
}
// 与login方法的第二个参数相同
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// 请求成功/失败返回该文案给用户展示，与login相同
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

const params: SendCodeParams = {
  email: '123456@qq.com',
  email_template_type: 'register_code'
}
  
rootauth?.sendCode(params)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

注意：验证码有 60 秒限制，请自行实现倒计时。

7.4 重置密码

interface ResetPasswordUParams {
  type?: string // 发验证码类型：EMAIL_CODE|PHONE_CODE，默认为邮箱验证码EMAIL_CODE，支持邮箱验证码EMAIL_CODE、手机验证码PHONE_CODE
  email?: string // 邮箱，type=EMAIL_CODE必填
  password: string // 新密码，注意：仅需要传入明文密码，RootAuth进行加密处理
  password_confirmation: string // 确认密码，注意：仅需要传入明文密码，RootAuth进行加密处理
  code: string
  phone_code?: string // 手机区号，type=PHONE_CODE必填，示例：86
  phone_num?: string // 手机号，type=PHONE_CODE必填
    
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
}
// 与login方法的第二个参数相同
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// 请求成功/失败返回该文案给用户展示，与login相同
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

const params: ResetPasswordUParams = {
  email: '123456@qq.com',
  password: '123456',
  password_confirmation: '123456',
  code: '111111'
}
  
rootauth?.resetPassword(params)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

7.5 第三方登录

interface ThirdPartyLoginParams {
  auth_by: string // 第三方类型：google_oauth|telegram|facebook，google_oauth：谷歌登陆、telegram：Telegram登陆、facebook：Facebook登陆
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
  response_type?: string // 返回形式，默认为code
}
// 请求成功/失败返回该文案给用户展示，与login相同
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

const params: ThirdPartyLoginParams = {
  auth_by: 'google_oauth'
  redirect_uri: '****/search'
}
  
rootauth?.thirdPartyLogin(params)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

7.6 Google One Tap 登录

需要在创建实例时开启配置enable_google_one_tap: true

const options: RootAuthClientConfig = {
  app_id: 'app_******', // 必填项，值为工作台创建应用生成的app_id
  enable_google_one_tap: true // 设为true才能开启one tap登陆
}
const client = new RootAuthClient(options)

client?.googleOneTapLogin()

7.7 MFA 二次验证

当工作台开启电子邮箱验证、OTP 验证或短信验证后，使用账号密码登录时，接口会返回 mfa_token 和 mfa_methods。根据 mfa_methods 的提示，调用 verifyLoginMfa 完成验证。

返回的 mfa_methods 含义：

mfa_methods 值	说明
`['EMAIL_BIND']`	需要绑定邮箱并验证
`['EMAIL']`	需要邮箱验证码
`['TOTP_BIND']`	首次绑定 OTP 验证器（会额外返回 `totp_secret`）
`['TOTP']`	输入 OTP 验证码
`['PHONE_CODE_BIND']`	需要绑定手机号并验证
`['PHONE_CODE']`	需要短信验证码

调用验证接口：

interface LoginMfaVerifyParams {
  mfa_token: string // 后端login接口返回的mfa_tokenn
  mfa_type: strig // 二次认证的类型：EMAIL|EMAIL_BIND|TOTP_BIND|TOTP|PHONE_CODE|PHONE_CODE_BIND，EMAIL：邮箱认证，EMAIL_BIND：邮箱绑定，TOTP_BIND：首次绑定OTP验证器，TOTP：OTP验证（已绑定验证器），PHONE_CODE：手机号认证，PHONE_CODE_BIND：手机号绑定
  code: string // 当mfa_type=EMAIL/EMAIL_BIND时，code为邮箱验证码；当mfa_type=TOTP/TOTP_BIND时，code为验证器上的验证码；当mfa_type=PHONE_CODE/PHONE_CODE_BIND时，code为短信验证码
  totp_bind_code?: string // 当mfa_type=TOTP_BIND时，填入的邮箱/手机验证码
  email?: string // 邮箱，type=EMAIL_BIND必填
  phone_code?: string // 手机区号，type=PHONE_CODE_BIND必填，示例：86
  phone_num?: string // 手机号，type=PHONE_CODE_BIND必填
    
  redirect_uri?: string // 登录之后跳转的路径，建议不设置，使用全局的redirect_uri
  scope?: string[] // 映射关系，建议不设置，使用全局的scope
  state?: string // 用户自定义参数，原样输出，建议不设置，使用全局的state
  grant_type?: string // 授权模式，建议不设置，使用全局的scope
  response_type?: string // 返回形式，默认为code
}
// 与login方法的第二个参数相同
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// 请求成功/失败返回该文案给用户展示，与login相同
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success、error、warning
    msg: string // 提示文案，已做多语言处理
  }
}

const params: LoginMfaVerifyParams = {
  mfa_token: 'fsdfsdf'
  mfa_type: 'EMAIL'
  code: '123456'
  email_code: '123456'
}
  
rootauth?.verifyLoginMfa(params)
.then((res) => {
  // 基于当前的RootAuth逻辑，补充自有逻辑
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

7.8 其他实用方法

方法	说明
`client?.getAppConfig()`	获取应用配置
`client?.logout()`	退出登录，清除 token
`client?.getToken()`	获取当前 token
`client?.isAuthenticated()`	判断是否已登录
`client?.setLocale('en-US')`	切换语言（zh-CN / en-US）语言优先级：API 模式优先使用 `new RootAuthClient({ locale })` 传入的值。

上一个

开发集成

下一个

Vue 模式接入

最近修改: 2026-06-10Powered by

大纲