JavaScript SDK

RootAuth provides a JavaScript SDK to help you quickly integrate authentication features such as login, registration, and authorization into your web application. The SDK supports two integration modes, allowing you to choose the one that best fits your project needs.

 

1. Integration Mode Overview

Common to both modes:

• An app must be created in the workspace to obtain an app_id

• A RootAuthClient instance must be created

 

2. Preparation

Create an app and obtain the app_id

1. Log in to the RootAuth workspace

2. Create or select your application

3. Copy the APP ID from the application configuration page (format: app_******)

3. Install the SDK

Run the following command in your project root to install the stable version:

npm install --save rootauth-js

Note: Do not download beta versions (test versions); use only stable releases.

 

4. Common Steps

Create a RootAuthClient instance

Create the client instance in your project’s entry file (e.g., main.js) and inject it into the global object as needed.

// main.js
import type { Router, RouteRecordRaw } from 'vue-router'
import { RootAuthClient, type RootAuthClientConfig } from 'rootauth-js'

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

Complete configuration options (RootAuthClientConfig)

interface RootAuthClientConfig {
  app_id: string // Required: obtained from the workspace application configuration
  mode?: 'api' | 'hosted'  // Usage mode, defaults to hosted (uses RootAuth pages)
  /** Base path for routes in hosted mode, e.g., '/auth' results in routes like /auth/login, /auth/register, etc.; if omitted, routes start from site root / */
  base_path?: string
  api_base_url?: string // Backend API endpoint path, defaults to https://rootauth-api.rootauth.com; for development, modify to https://rootauth-api.rootauth.dev
  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']
  grant_type?: string // Authorization mode, defaults to authorization_code
  enable_google_one_tap?: boolean // Enable Google One Tap login, defaults to false
  /** Hosted mode login success callback; returns false to prevent default redirect */
  onLoginSuccess?: LoginSuccessCallback;
  /** Hosted mode registration success callback; returns false to prevent default redirect */
  onRegisterSuccess?: RegisterSuccessCallback;
}

 

At this point, the common steps are complete. Continue configuration based on your chosen integration mode.

 

5. Hosted Mode

This mode is the default. It enables RootAuth’s complete login/registration/password reset pages.

 

5.1 Route Notes

Hosted mode reserves the following three routes. Avoid redefining them in your application routes:

• /login

• /register

• /reset-password

To customize the base path, use the base_path configuration option to add a prefix (e.g., setting it to /auth changes the routes to /auth/login, etc.).

 

5.2 Mounting Routes

Call the instance’s install method and pass your Vue Router instance. The SDK will automatically merge the authentication routes into your routing system.

// main.js
import type { Router, RouteRecordRaw } from 'vue-router'
import { RootAuthClient, type RootAuthClientConfig } from 'rootauth-js'

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

  client.install(router as Router)

 

5.3 Dynamic Language Switching

If you need to switch languages in your system, inject the client instance into the global object and call:

client?.setLocale('en-US')

 

5.4 Hosted Mode Complete Example

// main.js
import type { Router, RouteRecordRaw } from 'vue-router'
import { RootAuthClient, type RootAuthClientConfig } from 'rootauth-js'

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

  client.install(router as Router)

 

6. API Mode

This mode provides API calls only and includes no UI. You must implement your own login/registration pages and call the SDK methods to complete authentication.

 

6.1 Create a Client Instance

(You must specify mode: 'api')

import { RootAuthClient, type RootAuthClientConfig } from 'rootauth-js'

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

 

6.2 Inject the Global Instance

(Using Nuxt as an example)

For other frameworks (such as Vue, React), follow a similar approach: mount the client globally or use Context/Provider.

 

6.2.1 Create the Plugin File

plugins/rootauth.client.ts

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

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

 

6.2.2 Register the Plugin

nuxt.config.ts

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

 

6.2.3 Access the Instance in a Component

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

 

6.2.4 Wrap in a Composable (Optional, Recommended)

Create composables/useRootAuth.ts:

// composables/useRootAuth.ts
import type { RootAuthClient } from 'rootauth-js'

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

The  RootAuth object can now be used more cleanly:

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

 

6.3 API Method Notes

The login, register, sendCode, and resetPassword methods all return a Promise. A second parameter can be passed with custom callbacks (onSuccess/onFailure) to override the SDK’s default behavior.

If you only need to add extra logic (such as closing a loading indicator), use the Promise directly (.then(), .catch()) without passing the second parameter. The SDK will retain its default behavior.

6.3.1 Login

const rootauth = useRootAuth()

interface LoginParams {
  type: string // Required: login method: EMAIL_PASS|EMAIL_CODE, currently supports EMAIL_PASS (email + password) and EMAIL_CODE (email verification code)
  email: string // Required: user email
  password?: string // Required when type is EMAIL_PASS; note: only plaintext password is needed, RootAuth handles encryption
  code?: string // Required when type is EMAIL_CODE
}
interface RootAuthFlowCallbacks<T = unknown> {
  onSuccess?: (data: T) => void
  onFailure?: (error: unknown) => void
}

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

Example with custom callback:

const handleSubmit=()=>{
  // User handles pre-validation
  loading.value = true
  rootauth?.login({
    type:'EMAIL_PASS',
    email:'123456@qq.com',
    password:'123456'
  },
  {
    onSuccess:()=>{
      // Custom login success callback, including notifications, etc.
    },
    onFailure:()=>{
      // Custom login failure callback, including notifications, etc.
    }
  })
  .finally(() => {
    loading.value = false
  })
}

 

6.3.2 Register

interface RegisterParams {
  type?: string // Registration type: EMAIL_CODE, defaults to EMAIL_CODE (email verification code registration)
  email: string // Required: user email
  code: string // Required: email verification code
  password: string // Required: password; note: only plaintext password is needed, RootAuth handles encryption
}

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(() => {
})

 

6.3.3 Send Verification Code

interface SendCodeParams {
  type?: string // Verification code type: EMAIL, defaults to EMAIL (email verification code)
  email: string // Required: user email
  email_template_type: string // Required: template type: register_code|login_code|reset_pass_code; register_code: registration code, login_code: login code, reset_pass_code: password reset code
}

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(() => {
})

 

6.3.4 Reset Password

interface ResetPasswordUParams {
  type?: string // Verification code type: EMAIL_CODE, defaults to EMAIL_CODE (email verification code)
  email: string
  password: string // New password; note: only plaintext password is needed, RootAuth handles encryption
  password_confirmation: string // Confirm password; note: only plaintext password is needed, RootAuth handles encryption
  code: string
}

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(() => {
})

 

6.3.5 Third-Party Login (Google OAuth)

interface ThirdPartyLoginParams {
  auth_by: string // Third-party type: google_oauth; google_oauth: Google login
}

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

 

6.3.6 Google One Tap Login

You must first enable enable_google_one_tap: true in the configuration.

rootauth?.googleOneTapLogin()