API Mode Integration

@rootauth/core is the framework-free RootAuth SDK. It handles configuration, encryption, authentication requests, MFA, third-party login, session operations, and language switching, but does not render UI.

Preparation

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

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/

1. Installation

@rootauth/core is the UI-free base SDK for RootAuth authentication APIs, request configuration, sessions, and shared utilities. This section shows installation with npm.

npm install @rootauth/core

2. Create a client

The client stores shared options such as app_id, API URL, OIDC parameters, and locale. This section covers client creation, required options, and the complete configuration table.

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)

// Optional: preload and cache app config and the device fingerprint.
await rootAuth.install()

An install() preload failure does not block application startup. If it is omitted or the preload fails, login() and register() fetch the required data before submitting.

2.1 Configuration

3. Calling convention

Authentication methods return promises and selected flows also accept an onSuccess callback. Supplying the callback transfers success handling to the application, while failures throw normalized error objects.

Authentication methods return a Promise and accept an optional onSuccess callback:

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

When onSuccess is supplied, login and registration do not perform the SDK default redirect or automatic login; the application handles the result.

The following interfaces support this callback convention: sendCode(), login(), verifyLoginMfa(), register(), resetPassword(), and updateProfile().

const result = await rootAuth.login({
  type: 'EMAIL_PASS',
  email: 'user@example.com',
  password: 'password',
})

rootAuth.login(
  {
    type: 'EMAIL_PASS',
    email: 'user@example.com',
    password: 'password',
  },
  {
    onSuccess(result) {
      console.log(result)
    },
  }
)

Successful responses and errors may carry an SDK message:

interface RootAuthMessage {
  type: string
  msg: string
}

interface RootAuthMessageCarrier {
  rootauth_message?: RootAuthMessage
}

type is one of success, warning or error, msg is the final localized copy returned by the backend for the current locale.

Core renders no UI. The application must display messages from rootauth_message or error objects.

4. Login: login()

login() supports email, phone, username, verification-code, WhatsApp, and invitation login flows. This section lists every type, its authentication method, required fields, and examples.

4.1 Complete type list

4.2 Parameters

The caller must pass the correct type; the SDK does not infer the login method from supplied fields. When MFA follows login, loginAccountType is derived from this explicit login type. A TOTP account name is then selected from the matching account field: email for email login, phone for phone login, and username for username login.

await rootAuth.login({
  type: 'PHONE_CODE',
  phone_code: '86',
  phone_num: '13800000000',
  code: '123456',
})

5. Send a code: sendCode()

sendCode() sends codes for login, registration, password reset, and MFA flows. This section describes email, SMS, WhatsApp, and other type values with their required parameters.

If the error message Too many incorrect verification code attempts. Please request a new code. appears when requesting a verification code, go to Console > General Security > CAPTCHA Rules > CAPTCHA Attempt Count to check whether the configured limit meets your requirements.

5.1 Complete type list

5.2 email_template_type and phone_text_template_type values

5.3 Parameters

email_template_type is used only with EMAIL, and phone_text_template_type only with PHONE_TEXT. WHATSAPP does not use a template parameter.

await rootAuth.sendCode({
  type: 'EMAIL',
  email: 'user@example.com',
  email_template_type: 'register_code',
})

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

When CAPTCHA is enabled, the SDK runs Tencent CAPTCHA automatically. The business UI controls delivery frequency and the 60-second countdown.

6. Registration: register()

register() supports email, phone, username, and WhatsApp registration. This section lists registration type values, required fields, and complete code-registration calls.

6.1 Complete type list

6.2 Parameters

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

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

Passwords are encrypted with the application's RSA public key. Without onSuccess, the SDK may redirect based on the backend response or automatically log in when there is no redirect_url.

7. Reset password: resetPassword()

Password reset supports submitting a verification code directly or validating it first and then using the returned verify_token.

7.1 Verify code: verifyResetPasswordCode()

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

The response data contains verify_token.

7.2 Reset password: resetPassword()

At least one of code and verify_token is required.

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

8. MFA: verifyLoginMfa()

verifyLoginMfa() handles email, phone, and TOTP verification as well as first-time binding. This section explains each mfa_type, code content, and additional fields.

8.1 Parameters

await rootAuth.verifyLoginMfa({
  mfa_type: 'TOTP',
  code: '123456',
})

mfa_methods may contain multiple options. For TOTP_BIND, the login response may also contain totp_secret for QR-code generation.

9. Third-party login

Third-party authentication covers Google OAuth, Telegram, Facebook, VK, and WeChat Official Account QR flows. This section distinguishes redirects, Google One Tap, and QR polling, and clarifies that WhatsApp is not third-party OAuth.

9.1 thirdPartyLogin()

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

thirdPartyLogin() is only for Google OAuth, Telegram, Facebook, and VK. It obtains the authorization URL and redirects to the page configured by redirect_uri.

WhatsApp is not a third-party OAuth provider; both WhatsApp login and registration use login() or register() with type: 'WHATSAPP_CODE'.

9.2 Google One Tap

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

await rootAuth.googleOneTapLogin()

Google One Tap must be enabled in application configuration and requires Google's browser script and a valid client ID.

9.3 WeChat Official Account QR code

WeChat Official Account does not use thirdPartyLogin(). Call wechatServiceQrLogin() to obtain QR authorization data, then query the scan result with getThirdPartyQrResult() and the returned state_key.

const qr = await rootAuth.wechatServiceQrLogin()

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

Display qr.data.data.qr_url or authorize_url and use expire_seconds as the polling deadline. getThirdPartyQrResult() performs one query; the application must schedule polling and stop on success, expiry, or view disposal.

10. Session, configuration, and language

This section summarizes current-user lookup, logout, application configuration, and locale APIs. These supporting methods share the same Core client as login and registration.

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

11. Related modes

Applications that do not build every authentication screen can use Web Components, Vue Hosted, or React Hosted. This section links each integration and explains its level of UI ownership.

• @rootauth/web-components: standalone forms for any frontend stack.
• @rootauth/vue: complete hosted pages for Vue 3.
• @rootauth/react: complete hosted pages for React 18+.