Menu

API Mode Integration

RootAuth API Mode provides a pre-packaged frontend API interface without any UI. You are free to implement login, registration, and other pages according to your own design style, and call the SDK to complete the authentication logic.

 

1. Preparation

Create an application in the RootAuth Console and copy the app_id (format: app_******).

2. Prerequisite

Please add the following configuration line to the .npmrc file in the project root directory:

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

 

3. Install the SDK

Run the following command in your project root directory to install the dependency package:

npm install @rootauth/core
 

4. Create a RootAuthClient Instance

Create an instance in your entry file (e.g., main.js):

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

const options: RootAuthClientConfig = {
    app_id: 'app_******', // Required: app_id generated from the workspace
}
const client = new RootAuthClient(options)
 

4.1 Complete Configuration Options

RootAuthClientConfig

interface RootAuthClientConfig {
  app_id: string // Required: obtained from the workspace application configuration
  api_base_url?: string // Backend API endpoint path, defaults to https://rootauth-api.rootauth.com
  redirect_uri?: string // Redirect path after successful login, defaults to location.origin
  state?: string // Custom parameter, returned as-is by the API
  locale?: string // Current language, defaults to zh-CN; currently supports zh-CN, en-US
  scope?: string[]  // Scope mapping, defaults to ['openid']; add fields like avatar, username here
  grant_type?: string // Authorization mode, defaults to authorization_code
  enable_google_one_tap?: boolean // Enable Google One Tap login, defaults to false
}

Note: The mode parameter is deprecated in this version and should not be passed.

 

5. Inject the Global Instance

(Using Nuxt as an example)

For other frameworks (Vue, React, etc.), you can follow a similar approach and mount the client globally.

5.1 Create the Plugin File

plugins/rootauth.client.ts:

// plugins/rootauth.client.ts
import { RootAuthClient, type RootAuthClientConfig } from '@rootauth/core'
export default defineNuxtPlugin(() => {
  const options: RootAuthClientConfig = {
    app_id: 'app_******', // Required: app_id generated from the workspace
  }
  const client = new RootAuthClient(options)

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

5.2 Register the Plugin

nuxt.config.ts:

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

5.3 Access the Instance in a Component

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

5.4 Wrap in a Composable (Recommended)

composables/useRootAuth.ts:

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

/** RootAuth client (injected by `plugins/rootauth.client` when `ROOTAUTH_APP_ID` is configured) */
export function useRootAuth(): RootAuthClient | undefined {
  return useNuxtApp().$rootauth as RootAuthClient | undefined
}
 

Usage:

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

6. General Notes

  • Form validation: RootAuth does not perform frontend validation. Please validate before calling the API.

  • Password encryption: Only plaintext passwords are required; the SDK will encrypt them automatically.

  • Callback override: The second parameter callbacks of each method can accept onSuccess, which completely overrides the SDK’s default behavior. If you only need to add extra logic (e.g., closing a loading indicator), use the Promise chain (.then() / .catch()) directly without passing the second parameter.

  • Success / failure handling: Failed requests uniformly use Promise reject. Both success and failure responses include a rootauth_message object (containing type and msg), which is internationalized (Chinese/English). API mode does not automatically show any UI prompts; you must handle error displays yourself.

 

7. API Method Details

7.1 Login

This interface is also used when the workspace option “Combine Login and Registration” is selected.

const rootauth = useRootAuth()

interface LoginParams {
  type: string // Required: login method: EMAIL_PASS|EMAIL_CODE|PHONE_PASS|PHONE_CODE. Currently supports EMAIL_PASS (email+password), EMAIL_CODE (email verification code), PHONE_CODE (phone verification code), PHONE_PASS (phone+password)
  email: string // Required: user email
  password?: string // Required when type is EMAIL_PASS/PHONE_PASS; note: only plaintext password is required, RootAuth handles encryption
  code?: string // Required when type is EMAIL_CODE/PHONE_CODE

  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
}
// Second parameter of the login method
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// Success/failure response includes this message for user display
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

// Available type
rootauth?.login(
  params: LoginParams,
  callbacks?: RootAuthFlowCallbacks<RootAuthClientSuccessResponse<CustomerLoginResponse>>,
)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  // Handle request failures here
  console.log('err', err)
})
.finally(() => {
  // Close loading indicator, etc.
})
 

Example of overriding default behavior (passing the second parameter):

const handleSubmit = () => {
  // User handles pre-validation
  loading.value = true
  rootauth?.login({
    type: 'EMAIL_PASS',
    email: '123456@qq.com',
    password: '123456'
  },
  {
    onSuccess: (res) => {
      // Custom login success callback, including notifications, etc.
      if (res.rootauth_message.msg) {
        message[res.rootauth_message.type || 'success'](
          res.rootauth_message.msg
        )
      }
    }
  })
  .catch(err => {
    // Handle request failures here
    if (err.rootauth_message.msg) {
      message[err.rootauth_message.type || 'error'](
        err.rootauth_message.msg
      )
    }
  })
  .finally(() => {
    loading.value = false
  })
}
 

7.2 Register

interface RegisterParams {
  type?: string // Registration type: EMAIL_CODE_PASS|PHONE_CODE_PASS. Defaults to EMAIL_CODE_PASS (email verification code). Supports EMAIL_CODE_PASS and PHONE_CODE_PASS (SMS verification code)
  email?: string // User email, required when type=EMAIL_CODE_PASS
  code: string // Required: email/phone activation code
  password: string // Required: password; note: only plaintext password is required, RootAuth handles encryption
  phone_code?: string // Phone country code, required when type=PHONE_CODE_PASS, e.g., '86'
  phone_num?: string // Phone number, required when type=PHONE_CODE_PASS

  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
}
// Same as the second parameter of the login method
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// Success/failure response includes this message for user display, same as login
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

const params: RegisterParams = {
  email: '123456@qq.com',
  password: '123456',
  code: '123456',
}

rootauth?.register(params)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})
 

7.3 Send Verification Code

interface SendCodeParams {
  type?: string // Verification code type: EMAIL|PHONE_TEXT. Defaults to EMAIL. Supports EMAIL and PHONE_TEXT (SMS)
  email?: string // User email, required when type=EMAIL
  email_template_type?: string // Template type, required when type=EMAIL. Values: register_code|login_code|reset_pass_code|login_mfa_code. register_code and login_mfa_code: registration code; login_code: login code; reset_pass_code: password reset code; login_mfa_code: MFA login code
  phone_code?: string // Phone country code, required when type=PHONE_TEXT, e.g., '86'
  phone_num?: string // Phone number, required when type=PHONE_TEXT
  phone_text_template_type?: string // SMS template, required when type=PHONE_TEXT. Values: register_code|login_code|reset_pass_code|login_mfa_code. Supports register_code, login_code, reset_pass_code, login_mfa_code
  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
}
// Same as the second parameter of the login method
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// Success/failure response includes this message for user display, same as login
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

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

rootauth?.sendCode(params)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})

Note: Verification codes have a 60‑second cooldown. Please implement a countdown timer yourself.

 

7.4 Reset Password

interface ResetPasswordUParams {
  type?: string // Verification code type: EMAIL_CODE|PHONE_CODE. Defaults to EMAIL_CODE. Supports EMAIL_CODE and PHONE_CODE
  email?: string // Email, required when type=EMAIL_CODE
  password: string // New password; note: only plaintext password is required, RootAuth handles encryption
  password_confirmation: string // Confirm password; note: only plaintext password is required, RootAuth handles encryption
  code: string
  phone_code?: string // Phone country code, required when type=PHONE_CODE, e.g., '86'
  phone_num?: string // Phone number, required when type=PHONE_CODE

  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
}
// Same as the second parameter of the login method
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// Success/failure response includes this message for user display, same as login
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

const params: ResetPasswordUParams = {
  email: '123456@qq.com',
  password: '123456',
  password_confirmation: '123456',
  code: '111111'
}

rootauth?.resetPassword(params)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})
 

7.5 Third‑Party Login

interface ThirdPartyLoginParams {
  auth_by: string // Third-party type: google_oauth|telegram|facebook. google_oauth: Google login, telegram: Telegram login, facebook: Facebook login
  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
  response_type?: string // Response type, defaults to 'code'
}
// Success/failure response includes this message for user display, same as login
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

const params: ThirdPartyLoginParams = {
  auth_by: 'google_oauth',
  redirect_uri: '****/search'
}

rootauth?.thirdPartyLogin(params)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})
 

7.6 Google One Tap Login

You need to enable the enable_google_one_tap: true option when creating the instance.

const options: RootAuthClientConfig = {
  app_id: 'app_******', // Required: app_id generated from the workspace
  enable_google_one_tap: true // Set to true to enable One Tap login
}
const client = new RootAuthClient(options)

client?.googleOneTapLogin()


7.7 MFA Two‑Factor Verification

When email verification, OTP verification, or SMS verification is enabled in the workspace, the login API will return mfa_token and mfa_methods when logging in with email/password. Based on the mfa_methods hints, call verifyLoginMfa to complete verification.

Meanings of returned mfa_methods values:

mfa_methods value Description
['EMAIL_BIND'] Need to bind an email address and verify it
['EMAIL'] Need an email verification code
['TOTP_BIND'] First‑time binding of OTP authenticator (returns an extra totp_secret)
['TOTP'] Enter OTP verification code
['PHONE_CODE_BIND'] Need to bind a phone number and verify it
['PHONE_CODE'] Need an SMS verification code

 

Call the verification interface:

interface LoginMfaVerifyParams {
  mfa_token: string // mfa_token returned by the login API
  mfa_type: string // MFA type: EMAIL|EMAIL_BIND|TOTP_BIND|TOTP|PHONE_CODE|PHONE_CODE_BIND. EMAIL: email authentication; EMAIL_BIND: email binding; TOTP_BIND: first‑time OTP authenticator binding; TOTP: OTP verification (authenticator already bound); PHONE_CODE: phone authentication; PHONE_CODE_BIND: phone binding
  code: string // When mfa_type=EMAIL/EMAIL_BIND, code is the email verification code; when mfa_type=TOTP/TOTP_BIND, code is the authenticator code; when mfa_type=PHONE_CODE/PHONE_CODE_BIND, code is the SMS verification code
  totp_bind_code?: string // When mfa_type=TOTP_BIND, the email/phone verification code to be entered
  email?: string // Email, required when type=EMAIL_BIND
  phone_code?: string // Phone country code, required when type=PHONE_CODE_BIND, e.g., '86'
  phone_num?: string // Phone number, required when type=PHONE_CODE_BIND

  redirect_uri?: string // Redirect path after login; recommended to omit and use the global redirect_uri
  scope?: string[] // Scope mapping; recommended to omit and use the global scope
  state?: string // Custom parameter, returned as-is; recommended to omit and use the global state
  grant_type?: string // Authorization mode; recommended to omit and use the global grant_type
  response_type?: string // Response type, defaults to 'code'
}
// Same as the second parameter of the login method
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
}
// Success/failure response includes this message for user display, same as login
type RootAuthClientSuccessResponse {
  rootauth_message?: {
    type: string // success, error, warning
    msg: string // Prompt text, already internationalized
  }
}

const params: LoginMfaVerifyParams = {
  mfa_token: 'fsdfsdf',
  mfa_type: 'EMAIL',
  code: '123456',
  email_code: '123456'
}

rootauth?.verifyLoginMfa(params)
.then((res) => {
  // Add your own logic based on RootAuth's default behavior
})
.catch((err) => {
  console.error(err)
})
.finally(() => {
})
 

7.8 Other Utility Methods

Method Description
client?.getAppConfig() Get application configuration
client?.logout() Log out and clear the token
client?.getToken() Get the current token
client?.isAuthenticated() Check whether the user is logged in
client?.setLocale('en-US')

Switch language (zh-CN / en-US)

Language priority: In API mode, the value passed to new RootAuthClient({ locale }) takes precedence.

 

Previous
Develop the integration
Next
Vue Mode Integration
Last modified: 2026-06-10Powered by