authentication

Overview

The Auth Api provides a complete set of authentication-related features, supporting various log-in methods, user management, and session management. The Auth Api is divided into 7 categories by purpose. Each category contains related Api methods, helping developers quickly find suitable APIs depending on specific needs.

• Authentication login: API method related to user registration and login, supporting various login methods.
• Session management: API method to manage user session status and token.
• User management: API method to get, update, and manage user information.
• Identity source management: API method to manage binding and unbinding of third-party identity sources.
• Password management: API method for password reset and modification. -Verification management: API method for Captcha sending, verify, and resend.
• Other tools: API method for other auxiliary features.

---

Basic Usage Examples

Initialization Configuration

Publishable Key can go to Cloud Development Platform/API Key Configuration to generate

auth.detectSessionInUrl is an optional parameter for initialization. After configuration, it can automatically detect OAuth parameters (code, state) in the URL, suitable for usage scenarios such as signInWithOAuth and linkIdentity.

import cloudbase from "@cloudbase/js-sdk";

// Initialize it.
const app = cloudbase.init({
  env: "your-env-id", // Replace this value with your environment ID
  region: "ap-shanghai", // Region, defaults to Shanghai
  accessKey: "", // Fill in the generated Publishable Key
  auth: {
    detectSessionInUrl: true, // Optional: automatically detect OAuth parameters in the URL, suitable for signInWithOAuth, linkIdentity
  },
});

const auth = app.auth;

Login status check

Check login status
async function checkAuthStatus() {
  const { data, error } = await auth.getSession();

  if (error) {
console.error("Check login status failed:", error.message);
    return false;
  }

  if (data.session) {
console.log("user logged in:", data.session.user);
    return true;
  } else {
console.log("user not logged in");
    return false;
  }
}

User registration process

// User registration example (four-step verification process)
async function registerUser(email, password, verificationCode) {
Step 1: Send verification code
  const { data, error } = await auth.signUp({
    email: email,
    password: password,
  });

  if (error) {
console.error("Send Captcha failed:", error.message);
    return false;
  } else {
console.log("verification code sent, Validating...");

Step 2: Verify the Captcha and complete registration.
    const { data: loginData, error: loginError } = await data.verifyOtp({
      token: verificationCode,
    });

    if (loginError) {
console.error("Verification failed:", loginError.message);
      return false;
    } else {
console.log("register successfully:", loginData.user?.email);
      return true;
    }
  }
}

User logout

// User logout example
async function logoutUser() {
  const { data, error } = await auth.signOut();

  if (error) {
    console.error("Logout failed:", error.message);
    return false;
  } else {
    console.log("logout successful, session cleared");
    return true;
  }
}

Password login

// Password login example
async function loginWithPassword(email, password) {
  const { data, error } = await auth.signInWithPassword({
    email: email,
    password: password,
  });

  if (error) {
    console.error("Login failed:", error.message);
    return false;
  } else {
    console.log("Login successful:", data.user?.email);
    return true;
  }
}

Listen for authentication status

// Listen for authentication status adjustment
auth.onAuthStateChange((event, session, info) => {
  console.log("certification status transition:", event);

  switch (event) {
    case "INITIAL_SESSION":
      console.log("initial session established");
      if (session) {
        console.log("user logged in:", session.user);
      } else {
        console.log("user not logged in");
      }
      break;

    case "SIGNED_IN":
      console.log("user login successful:", session.user);
      break;

    case "SIGNED_OUT":
      console.log("user logged out");
      break;

    case "PASSWORD_RECOVERY":
      console.log("password reset");
      break;

    case "TOKEN_REFRESHED":
      console.log("Token refreshed");
      break;

    case "USER_UPDATED":
      console.log("user information updated");
      break;

    case "BIND_IDENTITY":
      console.log("identity source binding result");
      break;
  }
});

Mobile captcha login

// Complete mobile captcha login page implementation
class PhoneLoginPage {
  constructor() {
    this.setupEventListeners();
  }

// Set up event listening
  setupEventListeners() {
    document.getElementById("sendCodeBtn").addEventListener("click", (e) => {
      e.preventDefault();
      this.sendVerificationCode();
    });

    document.getElementById("verifyCodeBtn").addEventListener("click", (e) => {
      e.preventDefault();
      this.verifyCodeAndLogin();
    });
  }

// Send a Captcha
  async sendVerificationCode() {
    const phone = document.getElementById("phone").value;

    if (!phone) {
alert("Enter your phone number");
      return;
    }

// Verify phone number format
    if (!this.validatePhone(phone)) {
alert("Enter a valid mobile number format");
      return;
    }

// display loading...
    this.showLoading(true);
    this.hideError();

    try {
      const { data, error } = await auth.signInWithOtp({
        phone: phone,
      });

      if (error) {
        this.handleSendCodeError(error);
      } else {
        this.handleSendCodeSuccess(data);
      }
    } catch (error) {
      this.handleNetworkError(error);
    } finally {
      this.showLoading(false);
    }
  }

// Verify the Captcha and log in
  async verifyCodeAndLogin() {
    const code = document.getElementById("code").value;

    if (!code) {
alert("Enter the Captcha");
      return;
    }

    if (!this.verifyFunction) {
alert("Please first send verification");
      return;
    }

    this.showLoading(true);
    this.hideError();

    try {
      const { data, error } = await this.verifyFunction({ token: code });

      if (error) {
        this.handleVerifyError(error);
      } else {
        this.handleLoginSuccess(data);
      }
    } catch (error) {
      this.handleNetworkError(error);
    } finally {
      this.showLoading(false);
    }
  }

// Verify phone number format
  validatePhone(phone) {
    const phoneRegex = /^1[3-9]\d{9}$/;
    return phoneRegex.test(phone);
  }

// Handle sending Captcha successfully
  handleSendCodeSuccess(data) {
    this.verifyFunction = data.verifyOtp;

// Display the Captcha input area
    document.getElementById("verificationSection").style.display = "block";
    document.getElementById("phoneSection").style.display = "none";

// Start countdown
    this.startCountdown(60);

    document.getElementById("success").innerText =
The Captcha has been sent to your mobile phone. Please check your inbox.
    document.getElementById("success").style.display = "block";
  }

// Handle sending Captcha error
  handleSendCodeError(error) {
    switch (error.code) {
      case "invalid_phone":
        document.getElementById("error").innerText =
Incorrect phone number format, please check and retry.
        break;
      case "user_not_found":
        document.getElementById("error").innerText =
This phone number is unregistered. Please first register or use another phone number.
        break;
      case "resource_exhausted":
document.getElementById("error").innerText = "Frequency is too high, try again later";
        break;
      case "unreachable":
        document.getElementById("error").innerText =
Network connection failed. Check the network settings.
        break;
      default:
        document.getElementById("error").innerText =
"Send Captcha failed: " + error.message;
    }
    document.getElementById("error").style.display = "block";
  }

// Handle verification error
  handleVerifyError(error) {
    switch (error.code) {
      case "invalid_code":
document.getElementById("error").innerText = "Captcha error, please enter again";
        break;
      case "code_expired":
document.getElementById("error").innerText = "Captcha expired, please obtain again";
// Display the resend button
        document.getElementById("resendBtn").style.display = "block";
        break;
      case "max_attempts_exceeded":
document.getElementById("error").innerText = "Too many verification attempts, try again later";
        break;
      default:
        document.getElementById("error").innerText =
"Verification failed: " + error.message;
    }
    document.getElementById("error").style.display = "block";
  }

handle successful login
  handleLoginSuccess(data) {
document.getElementById("success").innerText = "Login successful. Welcome back";
    document.getElementById("success").style.display = "block";

console.log("user information:", data.user);
console.log("session information:", data.session);

Navigate to the homepage after a delay
    setTimeout(() => {
      window.location.href = "/dashboard";
    }, 2000);
  }

Handle network error
  handleNetworkError(error) {
    document.getElementById("error").innerText =
Network error, check the network and try again after.
    document.getElementById("error").style.display = "block";
console.error("network error:", error);
  }

// Show/Hide loading...
  showLoading(show) {
    document.getElementById("loading").style.display = show ? "block" : "none";
    document.getElementById("sendCodeBtn").disabled = show;
    document.getElementById("verifyCodeBtn").disabled = show;
  }

// Hide error message
  hideError() {
    document.getElementById("error").style.display = "none";
  }

// Start countdown
  startCountdown(seconds) {
    let countdown = seconds;
    const btn = document.getElementById("resendBtn");
    const originalText = btn.innerText;

    btn.disabled = true;

    const timer = setInterval(() => {
      countdown--;
btn.innerText = `${countdown}s to resend`;

      if (countdown <= 0) {
        clearInterval(timer);
        btn.disabled = false;
        btn.innerText = originalText;
      }
    }, 1000);
  }
}

// Initialize after the webpage loads
window.addEventListener("DOMContentLoaded", () => {
  new PhoneLoginPage();
});

---

Authentication login

signUp

async signUp(params: SignUpReq): Promise<SignUpRes>

Register new user account, use intelligent signup and login process.

Note

Phone number verification code registration is only supported in the Shanghai region

-Create a new user account -Use intelligent signup and login process: send verification code → wait for user input → intelligently determine user existence → automatically log in or register and log in. -If the user already exists, log in directly. If the user does not exist, register a new user and automatically log in.

参数

params

SignUpReq

email可选string

Email (or phone number)

phone可选string

Mobile number (or email)

password可选string

Password

username可选string

Username, length 5-24 characters, supports English case sensitivity, digits, special characters (only -_.:+@ allowed), and must start with a letter or digit. Chinese characters are not allowed.

anonymous_token可选string

Anonymous user access_token for anonymous user Promotion

返回

Promise

SignUpRes

dataSignUpResData

verifyOtp

可选

(params: verifyParams) => Promise<SignInRes>

Callback function for verification code, supports messageId parameter to validate user input Captcha

paramsverifyParams

input parameter of callback function for state changes

token

string

Captcha

messageId

可选

string

Captcha ID

returnPromise<SignInRes>

Back

data

SignInResData

userUser

User details, including identity information and metadata

sessionSession

Session information, including access token and refresh token

error

AuthError | null

Error info. null on success

errorAuthError | null

Error info. null on success

示例

---

signInAnonymously

async signInAnonymously(params?: SignInAnonymouslyReq): Promise<SignInRes>

Anonymous login, create a temporary anonymous user account.

-Create a temporary anonymous user account -No need to provide any authentication information -Suitable for scenarios where temporary access permission is required -Before using, please confirm that anonymous login (enabled by default) is enabled in Cloud Development Platform/Identity Verification/Registration Configuration.

参数

params

SignInAnonymouslyReq

provider_token可选string

Provide tokens for associating third-party platform identity

返回

Promise

SignInRes

dataSignInResData

user

User

Anonymous user info, including the is_anonymous flag

session

Session

Anonymous session information, including access token and refresh token

errorAuthError | null

Error info. null on success

示例

---

signInWithPassword

async signInWithPassword(params: SignInWithPasswordReq): Promise<SignInRes>

Log in with userName, mailbox, or phone number and password.

-Support username, mailbox, or mobile number in conjunction with password as log-in methods (choose one). -Before using, please confirm that username and password login (enabled by default) is enabled in Cloud Development Platform/Identity Verification/Regular Login.

参数

params

SignInWithPasswordReq

username可选string

Username, 5-24 characters in length, supports English case sensitivity, digits, special characters (only -_.:+@ allowed), and must start with a letter or digit. Chinese characters are not allowed (choose one from username, mailbox, or mobile number).

email可选string

Email address, used for email login method (choose one from username, email, or phone number)

phone可选string

Mobile number, used for mobile number-based login (choose one from username, mailbox, or mobile number).

passwordstring

User password, supports password strength verification and retry limit

is_encrypt可选boolean

Encrypted or not; false by default

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata

session

Session

Session information, including access token and refresh token

errorAuthError | null

Error info. null on success

示例

---

signInWithOtp

async signInWithOtp(params: SignInWithOtpReq): Promise<SignInWithOtpRes>

Use one-time password (OTP) for login validation, supporting mailbox and SMS verification.

Note

SMS verification code is only supported in the Shanghai region

• Send a one-time verification code via mailbox or mobile number for login validation.
• Support the full verification process: send Captcha → wait for user input → verify and log in.
• Suitable for passwordless login scenarios, offering higher security
• Before using, please confirm that log in via mailbox/SMS verification code is enabled in Cloud Development Platform/Identity Verification/Log-in Methods/Regular Login.
• If the user does not exist, a default registered user will be created. The automatic creation of the user can be controlled through the shouldCreateUser parameter, which is set to true by default

参数

params

SignInWithOtpReq

email可选string

Email address, used for email verification code login (choose one from email or phone number)

phone可选string

Mobile phone number, used for mobile verification code login (choose one from phone or email)

options可选SignInWithOtpReqOptions

optional parameters

shouldCreateUser

可选

boolean

if create user if not exists, default true

返回

Promise

SignInWithOtpRes

dataSignInWithOtpResData

verifyOtp

可选

(params: verifyParams) => Promise<SignInRes>

Callback function for verification code, supports messageId parameter to validate user input Captcha

paramsverifyParams

input parameter of callback function for state changes

token

string

Captcha

messageId

可选

string

Captcha ID

returnPromise<SignInRes>

Back

data

SignInResData

userUser

User details, including identity information and metadata

sessionSession

Session information, including access token and refresh token

error

AuthError | null

Error info. null on success

errorAuthError | null

Error info. null on success

示例

---

signInWithOAuth

async signInWithOAuth(params: SignInWithOAuthReq): Promise<SignInOAuthRes>

Generate authorization links for third-party platforms, supporting mainstream platforms such as WeChat and Google.

-Generate the authorization page URL for third-party platforms such as WeChat and Google. -Store status information in the browser session so that follow-up verification

• Support custom callback address and status parameter
• Before using, please confirm that the corresponding OAuth identity source is enabled in Cloud Development Platform/Identity Verification/Log-in Methods.

Must-Knows

• After calling this method, status information will be automatically saved to the browser session. When setting auth.detectSessionInUrl to true in cloudbase.init, it will automatically call verifyOAuth to verify after returning from a third-party callback, otherwise you need to manually verify via the verifyOAuth method subsequently.
• If no state parameter is provided, the system automatically generates a status parameter in prd-{provider}-{random string} format -The callback URL needs to be configured in the protected domains of the Cloud Development Platform, otherwise it will return a permission error.

参数

params

SignInWithOAuthReq

providerstring

Third-party platform flag, support wechat, google, github, facebook, apple

options可选SignInWithOAuthReqOptions

Configuration options

redirectTo

可选

string

Callback URL, defaults to the current page, need to configure in the protected domains

state

可选

string

Status parameter, used for security verification, defaults to a random string (format: prd-{provider}-{random string})

queryParams

可选

Record<string, string>

Additional query parameters, merged into the authorization URI

skipBrowserRedirect

可选

boolean

Whether to go to the authorization page, default false

type

可选

'sign_in' | 'bind_identity'

Type (optional), defaults to 'sign_in', sign_in: sign in, bind_identity: bind identity

返回

Promise

SignInOAuthRes

dataSignInOAuthResData

url

string

Authorization page URL, used to redirect to the third-party platform authorization page

provider

string

Third-party platform flag, used for subsequent verification and status management

errorAuthError | null

Error info. null on success

示例

---

signInWithIdToken

async signInWithIdToken(params: SignInWithIdTokenReq): Promise<SignInRes>

Log in with a third-party platform identity token, supporting mainstream platforms such as WeChat and Google.

-Log in with a third-party platform identity token, such as WeChat and Google. -Support specifying third-party platform identification. Third-party platforms must be configured in Cloud Development Platform/Identity Verification/Login Methods first. -Token is a required parameter

参数

params

SignInWithIdTokenReq

provider可选string

Third-party platform flag, support wechat, google, github, facebook, apple. Use common token verification when not specified

tokenstring

Identity token for third-party platforms, support various formats such as JWT and OAuth token

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata

session

Session

Session information, including access token and refresh token

errorAuthError | null

Error info. null on success

示例

signInWithCustomTicket

async signInWithCustomTicket(getTickFn: GetCustomSignTicketFn): Promise<SignInRes>

Use custom login invoice to log in, support complete custom login process.

-Use custom login ticket to authenticate -Support passing functions to obtain custom login invoice

• Suitable for scenarios requiring a complete custom login process
• For the detailed process of issuing a Ticket, see Custom Login

参数

getTickFn

GetCustomSignTicketFn

Function to get custom login invoice, return Promise<string>

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata

session

Session

Session information, including access token and refresh token

errorAuthError | null

Error info. null on success

示例

signInWithOpenId

async signInWithOpenId(params?: SignInWithOpenIdReq): Promise<SignInRes>

WeChat mini program OpenID silent login. If the user does not exist, it will determine whether to automatically register based on the login mode configuration of the corresponding identity source in the Cloud Development Platform login methods (https://tcb.cloud.tencent.com/dev?envId=#/identity/login-manage).

Note

Only supported for use in WeChat mini program

参数

params

SignInWithOpenIdReq

Login parameters

useWxCloud可选boolean

default value is true, true: use WeChat Cloud Development mode to handle request, need to open mini program TCB environment; false: use ordinary http request

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata, undefined when not logged in

session

Session

Session information, including access token and refresh token, undefined when not logged in

errorAuthError | null

Error info. null on success

示例

signInWithPhoneAuth

async signInWithPhoneAuth(params: SignInWithPhoneAuthReq): Promise<SignInRes>

WeChat mini program mobile phone authorization login. If the user does not exist, it will determine whether to automatically register based on the login mode configuration of the corresponding identity source in the Cloud Development Platform login methods (https://tcb.cloud.tencent.com/dev?envId=#/identity/login-manage).

Note

Only supported for use in WeChat mini program

参数

params

SignInWithPhoneAuthReq

Login parameters

phoneCodestring

WeChat mini program mobile number authorization code, obtained via the WeChat mini program rapid verification component

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata, undefined when not logged in

session

Session

Session information, including access token and refresh token, undefined when not logged in

errorAuthError | null

Error info. null on success

示例

Session Management

getSession

async getSession(): Promise<SignInRes>

Retrieve current session info and check user login status.

-Retrieve current user session information, including access token and user information. -Check whether the user is logged in. Returns an empty session if not logged in

参数

无参数

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata, undefined when not logged in

session

Session

Session information, including access token and refresh token, undefined when not logged in

errorAuthError | null

Error info. null on success

示例

---

refreshSession

async refreshSession(refresh_token?: string): Promise<SignInRes>

Refresh the session token, extend user login status, support auto-renewal and error recovery.

-Use a refresh token to get a new access token -Extend the valid period of user sessions -Supports the use of designated refresh tokens or default tokens

参数

refresh_token

string

refresh_tokenstring

Refresh token, by default uses the refresh token of the current session, supports customization

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata

session

Session

New session information, including access token and refresh token after update

errorAuthError | null

Error info. null on success

示例

---

setSession

async setSession(params: SetSessionReq): Promise<SignInRes>

Use existing access token and refresh token to set user session, support external system integration and manual session management.

-Use existing access_token and refresh_token to set user session -Suitable for scenarios where tokens are obtained from an external system and sessions are set manually. -Session set successfully triggers SIGNED_IN event

参数

params

SetSessionReq

access_token可选string

Access token for API call authentication and user authentication

refresh_tokenstring

Refresh token, which is used to obtain new access token and extend session valid period

返回

Promise

SignInRes

dataSignInResData

user

User

User details, including identity information and metadata

session

Session

Session information, including access token and refresh token

errorAuthError | null

Error info. null on success

示例

---

signOut

async signOut(params?: SignOutReq): Promise<SignOutRes>

User logout, clear the current session and local storage.

-Log out current user login status securely -Clear server-side session and local storage -Support redirect to specified page

• Trigger authentication status change event

参数

params

SignOutReq

options可选SignOutReqOptions

Logout configuration options

redirectTo

可选

string

Redirection address after logout, supports relative path and absolute URL

clearStorage

可选

boolean

Whether to clear local storage, default true, set as false to retain user preference

返回

Promise

SignOutRes

dataobject

Empty object, no special meaning

errorAuthError | null

Error info. null on success

示例

User Management

getUser

async getUser(): Promise<GetUserRes>

Obtain currently logged in user detailed information, include identity information, metadata and permission status, support user profile show and permission verification.

• Obtain currently logged in user complete information -including basic user information, metadata and identity information Users are advised to be logged in to obtain the complete information -Support checking user permissions and verification status

参数

无参数

返回

Promise

GetUserRes

dataGetUserResData

user

User

User details, including identity information, metadata and permission status

errorAuthError | null

Error info. null on success

示例

---

refreshUser

async refreshUser(): Promise<CommonRes>

Refresh current logged-in user information.

-Refresh current logged-in user complete information

• Re-fetch the latest user data from the server
• Suitable for scenarios where user information may be updated but local cache is unsynced User must be logged in to refresh info

参数

无参数

返回

Promise

CommonRes

dataCommonResData

user

User

Refreshed user information

session

Session

Refreshed session information

errorAuthError | null

Error info. null on success

示例

---

updateUser

async updateUser(params: UpdateUserReq): Promise<GetUserRes>

Update current logged-in user info.

-Password update not supported. Please use resetPasswordForEmail, resetPasswordForOld, or reauthenticate to update password. -Update current logged-in user basic info and metadata -Support updating mailbox, mobile number, username, nickname, avatar, etc. -Users are advised to be logged in to update information Return upon success after update user information

参数

params

UpdateUserReq

email可选string

Email address

phone可选string

mobile number

username可选string

Username, 5-24 characters in length, supports English case sensitivity, digits, special characters (only -_.:+@ allowed), and must start with a letter or digit. Chinese characters are not allowed.

description可选string

User description information

avatar_url可选string

avatar URL address

nickname可选string

user nickname

gender可选'MALE' | 'FEMALE'

user gender

返回

Promise

GetUserRes

dataGetUserResData

user

User

Updated user details

verifyOtp

可选

(params: verifyParams) => Promise<SignInRes>

Callback function for verification code, Captcha required when changing phone number or mailbox

paramsverifyParams

input parameter of callback function for state changes

token

string

Captcha

email

可选

string

Email

phone

可选

string

mobile number

returnPromise<SignInRes>

Back

data

SignInResData

userUser

User details, including identity information and metadata

error

AuthError | null

Error info. null on success

errorAuthError | null

Error info. null on success

示例

---

deleteUser

async deleteUser(params: DeleteMeReq): Promise<CommonRes>

Delete the current logged-in user account.

-Permanently delete the current logged-in user account. -Verify user password to confirm identity -Once deleted, all user data will be permanently removed. -Irreversible operation. Use with caution.

参数

params

DeleteMeReq

passwordstring

User password for identity authentication

返回

Promise

CommonRes

dataCommonResData

empty object

object

No special meaning

errorAuthError | null

Error info. null on success

示例

Identity Source Management

getUserIdentities

async getUserIdentities(): Promise<GetUserIdentitiesRes>

Retrieve all identity sources bound to the current user.

-Retrieve all third-party identity sources. Related identity sources can be configured in Cloud Development Platform/Identity Verification/Login Methods. -Return the detailed information of the identity source, including platform identifier, identity source ID, binding time.

• Users must be logged in to retrieve identity source information.

参数

无参数

返回

Promise

GetUserIdentitiesRes

dataGetUserIdentitiesResData

identities

Array<Identity>

Identity source information list

errorAuthError | null

Error info. null on success

示例

---

linkIdentity

async linkIdentity(params: LinkIdentityReq): Promise<LinkIdentityRes>

Bind a new identity source to the current user, and it will automatically redirect to the third-party OAuth authorization page.

• Bind a new third-party identity source to the current logged-in user. It supports binding third parties such as WeChat, Google, and GitHub. The identity source needs to be configured in Cloud Development Platform/Identity Verification/Login Methods first. -Binding succeeded. Users can use this identity source to log in.
• User must be logged in to bind an identity source.
• When setting auth.detectSessionInUrl to true in cloudbase.init, it will automatically call verifyOAuth to verify after returning from a third-party callback, otherwise you need to manually verify via the verifyOAuth method subsequently.

参数

params

LinkIdentityReq

providerstring

Identity source flag, such as wechat, google, github

返回

Promise

LinkIdentityRes

dataLinkIdentityResData

provider

string

Bound identity source flag

errorAuthError | null

Error info. null on success

示例

---

unlinkIdentity

async unlinkIdentity(params: UnlinkIdentityReq): Promise<CommonRes>

Unbind the identity source bound to the current user.

-Unbind the third-party identity source bound to the current logged-in user. Related identity sources can be configured in Cloud Development Platform/Identity Verification/Login Methods. -Unbinding is successful. Reload the identity source list. -Use the identity source flag (provider) instead of the identity source ID (identity_id) to proceed with unbinding.

参数

params

UnlinkIdentityReq

providerstring

Identity source flag, such as wechat, google, github

返回

Promise

CommonRes

dataCommonResData

empty object

object

No special meaning

errorAuthError | null

Error info. null on success

示例

Password Management

resetPasswordForEmail

async resetPasswordForEmail(email: string): Promise<ResetPasswordForEmailRes>

Resetting user password via mailbox, using a four-step verification process.

-Sending Captcha via mailbox to reset user password -Use a four-step verification process: send verification code → wait for user input → verify verification code → set new password. -User email must be registered and verified.

参数

email

string

Email address for user registration

返回

Promise

ResetPasswordForEmailRes

dataResetPasswordForEmailResData

updateUser

(attributes: UpdateUserAttributes) => Promise<SignInRes>

Callback function for verification code, supports new password parameter

attributesUpdateUserAttributes

input parameter of callback function for state changes

nonce

string

Captcha

password

string

New password

returnPromise<SignInRes>

Back

data

SignInResData

userUser

User details, including identity information and metadata

sessionSession

Session information, including access token and refresh token

error

AuthError | null

Error info. null on success

error

AuthError | null

Error info. null on success

示例

---

resetPasswordForOld

async resetPasswordForOld(params: ResetPasswordForOldReq): Promise<SignInRes>

Reset the password of the current logged-in user using the old password.

-Reset the password of the current logged-in user by verifying the old password. -Users are advised to be logged in -Suitable for scenarios where users remember the old password

参数

params

ResetPasswordForOldReq

new_passwordstring

New password

old_passwordstring

Old password

返回

Promise

SignInRes

dataSignInResData

user

User

Updated user information

session

Session

Updated session information

errorAuthError | null

Error info. null on success

示例

---

reauthenticate

async reauthenticate(): Promise<ReauthenticateRes>

Re-authenticate the current logged-in user identity through verification code verification and allow the modification of the password.

Note

SMS verification code is only supported in the Shanghai region

-Re-authenticate the present logged-in user identity and support update password. -Verify by sending a verification code to the user's registered mailbox or mobile number, giving priority to the mailbox. If the mailbox is not set by the user, use the mobile number. -Applicable to identity verification before security-sensitive operations

参数

无参数

返回

Promise

ReauthenticateRes

dataReauthenticateResData

updateUser

(attributes: UpdateUserAttributes) => Promise<SignInRes>

Callback function for verification code, supports new password parameter

attributesUpdateUserAttributes

input parameter of callback function for state changes

nonce

string

Captcha

password

可选

string

New password, if the input will update password

returnPromise<SignInRes>

Back

data

SignInResData

userUser

User details, including identity information and metadata

sessionSession

Session information, including access token and refresh token

error

AuthError | null

Error info. null on success

errorAuthError | null

Error info. null on success

示例

Verification Management

verifyOAuth

async verifyOAuth(params?: VerifyOAuthReq): Promise<SignInRes>

Verify third-party platform authorization callback and complete the OAuth login process.

-Verify third-party platform authorization callback, retrieve user information and complete login, can be used in conjunction with signInWithOAuth

• Support automatically obtaining authorization code and status parameter from URL parameter -Provide complete security verification mechanism to prevent CSRF attack

参数

params

VerifyOAuthReq

code可选string

Authorization code (default from URL parameter access)

state可选string

Status parameter (default from URL parameter access)

provider可选string

Third-party platform flag (default from sessionStorage retrieval)

返回

Promise

SignInRes

dataSignInResData

user

User

User information

session

Session

Session information

errorAuthError | null

Error info. null on success

示例

---

verifyOtp

async verifyOtp(params: VerifyOtpReq): Promise<SignInRes>

Verify the one-time password (OTP) to complete login or sign-up process.

Note

SMS verification code is only supported in the Shanghai region

-Verify the one-time password (OTP) sent to your mailbox or mobile number. -Support two verification methods: mailbox or mobile number (choose one).

• After successful verification, automatically log in the user and return session information
• Suitable for registration, login, password reset, and other scenarios

参数

params

VerifyOtpReq

email可选string

Email address (or phone number)

phone可选string

Phone number (or email)

tokenstring

Captcha

messageIdstring

Captcha ID

返回

Promise

SignInRes

dataSignInResData

user

User

User information

session

Session

Session information

errorAuthError | null

Error info. null on success

示例

---

resend

async resend(params: ResendReq): Promise<ResendRes>

Resend Captcha to mailbox or mobile number.

Note

SMS verification code is only supported in the Shanghai region

-Resend Captcha to user's mailbox or mobile number -Support registration, mailbox update, mobile number update, and other scenarios -Resend to get a new message ID for the verification process -Provide rate limit protection to prevent malicious resend

参数

params

ResendReq

email可选string

Email address (or phone number)

phone可选string

Phone number (or email)

type可选string

Captcha type, available values: 'signup' | 'email_change' | 'phone_change' | 'sms'

返回

Promise

ResendRes

dataResendResData

messageId

string

message ID (Captcha ID)

errorAuthError | null

Error info. null on success

示例

Other tools

onAuthStateChange

onAuthStateChange(callback: OnAuthStateChangeCallback): OnAuthStateChangeResult

Listen for authentication status changes and respond to events such as login, logout, and token refresh in real time.

• Listen for user authentication status change events -Support various event types: login, logout, token refresh, user information update, identity source bind. -Return the subscription object for cancel listening -Suitable to build responsive UI and status management

参数

callback

OnAuthStateChangeCallback

callback function for state changes

paramsOnAuthStateChangeCallbackParams

input parameter of callback function for state changes

event

OnAuthStateChangeEvent

event indication, including 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'PASSWORD_RECOVERY' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'BIND_IDENTITY'

session

Session

Session information, including access token and refresh token

info

可选

Info

callback information. If info.error exists, it indicates callback failure

type'sign_in' | 'bind_identity' | ''

Type, sign_in: sign in, bind_identity: bind identity

errorAuthError

not null, it indicates callback execution failure, such as login failure (Type: sign_in) or identity binding failure (Type: bind_identity)

returnvoid

function return of callback for state changes

返回

OnAuthStateChangeResult

object

dataOnAuthStateChangeResultData

subscription

Subscription

subscription object for cancel listening

idstring

Subscription ID

callbackOnAuthStateChangeCallback

callback function, identical to the passed parameter callback

unsubscribe() => void

Unsubscription method

示例

---

getClaims

async getClaims(): Promise<GetClaimsRes>

Retrieve the claim info from the current access token for debug and permission check.

-Parse the JWT claim info in the current access token -Return the header, claim, and signature of the token. -For debug token info, check permissions and verify token status. -Users are advised to be logged in to obtain token info

参数

无参数

返回

Promise

GetClaimsRes

dataGetClaimsResData

claims

Record<string, any>

token claim info

issstring

issuer

substring

subject

audstring

audience

expnumber

expiration time

iatnumber

issued at

at_hashstring

access token hash

namestring

Name

picture可选string

avatar URL

email可选string

Email

phone_number可选string

mobile number

scopestring

Authorization scope

project_idstring

Project ID

provider可选string

Third-party platform flag

provider_type可选string

Third-party platform type

groups可选string[]

User group

meta可选Record<string, any>

wxOpenId

可选

string

wxUnionId

可选

string

user_idstring

uid

rolesstring[]

Role

user_typestring

User type

client_typestring

Client type

is_system_adminboolean

System admin

header

Record<string, any>

Token header info

algstring

Encryption algorithm

kidstring

Token ID

signature

string

Token signature

errorAuthError | null

Error info. null on success

示例

toDefaultLoginPage

async toDefaultLoginPage(params: authModels.ToDefaultLoginPage): Promise<void>

Redirect to the default login page, fully compatible with web and WeChat mini program.

-Support redirection to the system default login page -Compatible with Web and WeChat mini program.

• Configurable login page version and redirect address
• Support carrying custom parameters and redirect

Local debugging

If you develop a Web application, since the static resources of the __auth login page are stored in Website Hosting, you need to configure a proxy during local debugging to successfully redirect to the __auth login page.

Recommended to use the Whistle tool to configure proxy. The access domain of the __auth login page can be viewed in Static Website Hosting - Configuration Message - Default Domain Name.

Assuming the access address of the locally started application is http://localhost:3000 and the access domain of the __auth login page is lowcode-xxx-xxx.tcloudbaseapp.com, the Whistle proxy Rules configuration is as follows:

https://lowcode-xxx-xxx.tcloudbaseapp.com http://localhost:3000

# Configure proxy for other application paths

After running the application, you can access it at https://lowcode-xxx-xxx.tcloudbaseapp.com.

参数

params

ToDefaultLoginPageReq

config_version可选string

Login configuration version for the default login page, default value 'env'

redirect_uri可选string

Redirection address after login, defaults to the current page address

app_id可选string

Application id

query可选object

Parameters to carry when navigating to the default login page

返回

Promise

CommonRes

dataCommonResData

empty object

object

No special meaning

errorAuthError | null

Error info. null on success

示例

Error Code

Login error

Error Code	Description
not_found	User does not exist
password_not_set	The current user has not set a password. Please use Captcha or third-party login method
invalid_password	Incorrect Password
user_pending	User not activated
user_blocked	User disabled
invalid_status	You have exceeded the maximum number of retries for password, please retry later
invalid_two_factor	MFA code mismatched or outdated

Registration error

Error Code	Description
failed_precondition	The mobile number or mailbox you input has been registered, please use another number

Captcha Related Errors

Error Code	Description
failed_precondition	Failed to obtain user information from third party
resource_exhausted	Attempt too frequent, try again later
invalid_argument	The input Captcha is incorrect or expired
aborted	Too many attempts, back to homepage and try again later
permission_denied	Your current session expired, back and retry
captcha_required	Need to enter Captcha, based on anti-robot service access
captcha_invalid	Incorrect Captcha, based on anti-robot service access

Other Errors

Error Code	Description
unreachable	Network error, check your network connection and try again later

Error Description

Error Code	Error Description	Description
permission_denied	cors permission denied, please check if {url} is in your client {env} domains	please check whether the secure domain name {url} is already configured for the {env} environment in "cloud Development Platform/Environment Configuration/Secure source/Protected domains" (https://tcb.cloud.tencent.com/dev?envId=#/env/safety-source). It will take effect 10 minutes after configuration.

---

Complete type definition

SignInAnonymouslyReq

Anonymous login parameter
interface SignInAnonymouslyReq {
provider_token?: string; // Provider token (optional)
}

User

interface User {
id: any; // User ID
aud: string; // Audience
role: string[]; // User role
email: any; // Email
email_confirmed_at: string; // Email confirmation time
phone: any; // Phone number
phone_confirmed_at: string; // Mobile number confirmation time
confirmed_at: string; // Confirmation time
last_sign_in_at: string; // Last login time
  app_metadata: {
app_metadata: {
provider: any; // Provider
providers: any[]; // Provider list
  };
  user_metadata: {
user_metadata: {
name: any; // Name
picture: any; // Avatar
username: any; // Username
gender: any; // Gender
locale: any; // Region
uid: any; // User ID
nickName: any; // Nickname
avatarUrl: any; // Avatar URL
location: any; // Location
hasPassword: any; // Whether there is a password
  };
identities: any; // Identity information
created_at: string; // Creation time
updated_at: string; // Update time
is_anonymous: boolean; // Anonymous or not
  // Add a field.
recovery_sent_at?: string; // Password reset send time
email_change_sent_at?: string; // Email change send time
phone_change_sent_at?: string; // Phone number change send time
new_email?: string; // New email address
new_phone?: string; // New phone number
}

Session

interface Session {
  access_token: string; // Access token
  refresh_token: string; // Refresh token
  expires_in: number; // Expiration time (seconds)
  token_type: string; // Token type
  user: User; // User information
  // Add a field.
  provider_token?: string; // Third-party platform token
  provider_refresh_token?: string; // Third-party platform refresh token
  expires_at?: number; // Expiry timestamp
  issued_at?: number; // Issuance timestamp
  scope?: string; // Authorization scope
  token_id?: string; // Token ID
}

AuthError

// Authentication error type
interface AuthError extends Error {
  code: (string & {}) | undefined; // Error code
  status: number | undefined; // HTTP Status Code
  // Common error codes
  // 400: Client Error
  // - invalid_email: incorrect email format
  // - invalid_phone: incorrect phone number format
  // - invalid_password: Invalid password format
  // - user_not_found: User does not exist
  // - email_already_exists: Email already exists
  // - phone_already_exists: Mobile number already exists
  // - username_already_exists: Username already exists
  // - invalid_code: Invalid verification code
  // - code_expired: Captcha expired
  // - max_attempts_exceeded: Too many verification attempts
  // - password_too_weak: Password strength is insufficient
  // - invalid_token: Token invalid
  // - token_expired: Token expired
  // - state_mismatch: State parameter mismatch
  // - provider_not_supported: Unsupported third-party platform
  // - provider_mismatch: Third-party platform flag mismatch
  // - failed_precondition: Precondition failed
  // - permission_denied: Insufficient permissions
  // - resource_exhausted: Resource exhaustion
  // - unreachable: Network connection failed
  // 500: Server Error
  // - internal_error: Internal Server Error
  // - service_unavailable: Service unavailable
}

CommonRes

// Common response parameters
interface CommonRes {
  data: {}; // empty object on success
  error: AuthError | null; // Error info. null on success
}

SignUpReq

// User registration parameters (four-step verification process)
interface SignUpReq {
  email?: string; // Email address (optional, choose either this or mobile number)
  phone?: string; // Mobile number (optional, choose either this or email address)
  password: string; // Password (required)
  username?: string; // Username (optional), length 5-24 characters, supports Chinese and English letters, numbers, special characters (only _- allowed), Chinese characters are not allowed
  nickname?: string; // Nickname (optional)
  avatar_url?: string; // Avatar URL (optional)
  gender?: "MALE" | "FEMALE"; // Gender (optional)
}

SignOutReq

// User logout parameter
interface SignOutReq {
  options?: {
    // Configuration option (optional)
    redirectTo?: string; // Redirection address after logout
    clearStorage?: boolean; // Whether to clear local storage (default true)
  };
}

SignInWithPasswordReq

// Password login parameter
interface SignInWithPasswordReq {
  username?: string; // Username (optional, choose one among username, mailbox, or phone number), length 5-24 characters, supports Chinese and English letters, numbers, special characters (only _- allowed), Chinese characters are not allowed
  email?: string; // Email address (optional, choose one among email address, username, or mobile number)
  phone?: string; // Mobile number (optional, choose one among mobile number, username, or email address)
  password: string; // Password (required)
  is_encrypt?: boolean; // Encrypted or not; false by default
}

SignInWithIdTokenReq

// ID token login parameter
interface SignInWithIdTokenReq {
  provider?: string; // Third-party platform flag (optional)
  token: string; // Third-party platform identity token (required)
  // Add a field.
  provider?: string; // Third-party platform flag (optional, duplicate parameter with provider, reserved for compatibility)
}

SignInWithOtpReq

// OTP login parameter
interface SignInWithOtpReq {
  email?: string; // Email address (optional, choose either this or mobile number)
  phone?: string; // Mobile number (optional, choose either this or email address)
  options?: {
    shouldCreateUser?: boolean; // If the user does not exist, create a new user, default true
  };
}

SignInWithOAuthReq

// OAuth authorization parameter
interface SignInWithOAuthReq {
  provider: string; // Third-party platform flag (required)
  options?: {
    // Configuration option (optional)
    redirectTo?: string; // Callback URL, defaults to current page
    skipBrowserRedirect?: boolean; // Whether to navigate to the authorization page, default false
    state?: string; // Status parameter, used for security verification, defaults to a random string (format: prd-{provider}-{random string})
    queryParams?: Record<string, string>; // Additional query parameters, which will be merged into the authorization URI
    type?: "sign_in" | "bind_identity"; // Type (optional), defaults to 'sign_in', sign_in: sign in, bind_identity: bind identity
  };
}

SetSessionReq

// Session setting parameter
interface SetSessionReq {
  access_token: string; // Access token (required)
  refresh_token: string; // Refresh token (required)
}

VerifyOAuthReq

// OAuth verification parameter
interface VerifyOAuthReq {
  code?: string; // Authorization code (optional, default from URL parameter access)
  state?: string; // Status parameter (optional, default from URL parameter access)
  provider?: string; // Third-party platform flag (optional, default from session retrieval)
}

VerifyOtpReq

// OTP verification parameter
interface VerifyOtpReq {
  type?:
    | "sms"
    | "phone_change"
    | "signup"
    | "invite"
    | "magiclink"
    | "recovery"
    | "email_change";
  email; // Validation type (optional)
  email?: string; // Email address (optional, choose either this or mobile number)
  phone?: string; // Mobile number (optional, choose either this or email address)
  token: string; // Captcha (required)
  messageId: string; // ID corresponding to the verification code (required)
}

UpdateUserReq

// User information update parameters
interface UpdateUserReq {
  email?: string; // Email address
  phone?: string; // Phone number
  username?: string; // Username (optional), length 5-24 characters, supports Chinese and English letters, numbers, special characters (only _- allowed), Chinese characters are not allowed
  description?: string; // Description (optional)
  avatar_url?: string; // Avatar URL (optional)
  nickname?: string; // Nickname (optional)
  gender?: "MALE" | "FEMALE"; // Gender (optional)
}

LinkIdentityReq

// Identity source bind parameter
interface LinkIdentityReq {
  provider: string; // Identity source flag (required)
}

UnlinkIdentityReq

// Identity source unbind parameter
interface UnlinkIdentityReq {
  provider: string; // Identity source flag (required)
}

ReauthenticateReq

// Re-authenticate parameter
interface ReauthenticateReq {
  // No input parameters, use the current logged-in user info
}

ResendReq

// Resend verification code parameter
interface ResendReq {
  email?: string; // Email address (optional, choose either this or mobile number)
  phone?: string; // Mobile number (optional, choose either this or email address)
  type?: "signup" | "email_change" | "phone_change" | "sms"; // Type (optional)
}

ResendRes

// Resend verification code response parameter
interface ResendRes {
  data: {
    messageId?: string; // Message ID (Captcha ID)
  };
  error: AuthError | null; // Error info. null on success
}

SignInWithOtpRes

// OTP login response parameter
interface SignInWithOtpRes {
  data: {
    verifyOtp?: (params: {
      token: string;
      messageId?: string;
    }) => Promise<SignInRes>; // Captcha callback function, supports messageId parameter
  };
  error: AuthError | null; // Error info. null on success
}

SignUpRes

// User registration response parameter
interface SignUpRes {
  data: {
    verifyOtp?: (params: {
      token: string;
      messageId?: string;
    }) => Promise<SignInRes>; // Captcha callback function, supports messageId parameter
  };
  error: AuthError | null;
}

SignInOAuthRes

// OAuth authorization response parameter
interface SignInOAuthRes {
  data: {
    url?: string; // Authorization page URL
    provider?: string; // Third-party platform flag
    scopes?: string; // Authorization scope
  };
  error: AuthError | null; // Error info. null on success
}

LinkIdentityRes

// Identity source bind response parameter
interface LinkIdentityRes {
  data: {
    provider?: string; // Bound identity source flag
    type?: "sign_in" | "bind_identity" | ""; // Type (optional), defaults to 'sign_in', sign_in: sign in, bind_identity: bind identity
  };
  error: AuthError | null; // Error info. null on success
}

Identity

interface Identity {
  id: string; // Identity source flag
  name: string; // Identity source name
  picture: string; // Avatar URL
}

GetUserIdentitiesRes

// Identity source retrieval response parameter
interface GetUserIdentitiesRes {
  data: {
    identities?: Array<{
      id: string; // Identity source flag
      name: string; // Identity source name
      picture: string; // Avatar URL
    }>;
  };
  error: AuthError | null; // Error info. null on success
}

GetClaimsRes

// Declaration information acquisition response parameter
interface GetClaimsRes {
  data: {
    // token claim info
    claims?: {
      iss: string; // issuer
      sub: string; // subject
      aud: string; //  audience
      exp: number; //  expiration time
      iat: number; // issued at
      at_hash: string; // access token hash
      name: string; // Name
      picture?: string; // Avatar URL
      email?: string; // Email
      phone_number?: string; // Phone number
      scope: string; // Authorization scope
      project_id: string; // Project ID
      provider?: string; // Third-party platform flag
      provider_type?: string; // Third-party platform type
      groups?: string[]; // User group
      meta?: {
        wxOpenId?: string;
        wxUnionId?: string;
      };
      user_id: string; // uid
      roles: string[]; // Role
      user_type: string; // Type of user
      client_type: string; // Client type
      is_system_admin: boolean; // System admin
    };
    // token header information
    header?: {
      alg: string; // Encryption algorithm
      kid: string; // Token ID
    };
    signature?: string; // Token signature
  };
  error: AuthError | null; // Error info. null on success
}

ResetPasswordForOldReq

// Reset password parameter with old password
interface ResetPasswordForOldReq {
  new_password: string; // New password (required)
  old_password: string; // Old password (required)
}

DeleteMeReq

// Current user deletion parameter
interface DeleteMeReq {
  password: string; // User password (required)
}

SignInRes

// Login response parameter
interface SignInRes {
  data: {
    user?: User; // User information
    session?: Session; // Session information
  };
  error: AuthError | null; // Error info. null on success
}

GetUserRes

// User information retrieval response parameter
interface GetUserRes {
  data: {
    user?: User; // User details
  };
  error: AuthError | null; // Error info. null on success
}

OnAuthStateChangeEvent

// Authentication status change event type
type OnAuthStateChangeEvent =
  | "SIGNED_OUT" // User logged out
  | "SIGNED_IN" // User login successful
  | "INITIAL_SESSION" // Initial session established
  | "PASSWORD_RECOVERY" // Password reset
  | "TOKEN_REFRESHED" // Token refreshed
  | "USER_UPDATED" // User information updated
  | "BIND_IDENTITY"; // Identity source binding result

OnAuthStateChangeCallback

// Authentication status change callback function type
type OnAuthStateChangeCallback = (
  event: OnAuthStateChangeEvent,
  session: Session
) => void;

ResetPasswordForEmailRes

// Mailbox password reset response parameter
interface ResetPasswordForEmailRes {
  data: {
    updateUser?: (attributes: UpdateUserAttributes) => Promise<SignInRes>; // Captcha callback function, supports new password parameter
  };
  error: AuthError | null; // Error info. null on success
}

UpdateUserAttributes

// User attribute update parameters
interface UpdateUserAttributes {
  nonce: string; // Captcha
  password: string; // New password
}

ReauthenticateRes

// Re-authenticate response parameter
interface ReauthenticateRes {
  data: {
    updateUser?: (attributes: UpdateUserAttributes) => Promise<SignInRes>; // Captcha callback function, supports new password parameter
  };
  error: AuthError | null; // Error info. null on success
}