Cloudbase Auth

When to use this skill

Use this skill whenever the task involves authentication or user identity in a CloudBase project, for example:

• Designing which login methods to support (anonymous, username/password, SMS, email, WeChat, custom login)
• Implementing auth with Web SDK (@cloudbase/js-sdk@2.x) on the frontend
• Working with Node SDK for user info, admin operations, or issuing custom login tickets
• Calling HTTP auth APIs directly from any backend or script
• Understanding tokens, login state, and auth-related best practices

If the task is not about authentication (e.g. only about database or storage), this skill is probably not needed.

Quick orientation

CloudBase Auth v2 provides:

• Multiple login methods with a unified user identity system
• Clear user types (internal, external, anonymous) and account linking
• A token-based session model with JWT access tokens and refresh tokens
• SDKs (Web, Node) and HTTP APIs that expose the same core flows

This SKILL.md acts as a launcher. For deeper details, read the linked files only as needed.

Table of contents (progressive disclosure)

1. Concepts & design

• concepts/overview.md – what CloudBase Auth v2 is, high-level architecture, and where to configure it.
• concepts/login_methods.md – supported login methods, when to use each, and tradeoffs.
• concepts/user_accounts_and_roles.md – internal vs external vs anonymous users, UIDs, and multi-account linking.
• concepts/tokens_and_sessions.md – access_token vs refresh_token, v1 vs v2, and validation.

2. Web SDK (@cloudbase/js-sdk@2.x)

• web-sdk/web_quickstart.md – install/init SDK, get auth instance, basic sign-up/sign-in flow.
• web-sdk/web_login_flows.md – concrete flows for:
• Username/password
• SMS verification code login
• Email verification code login
• Anonymous login and upgrade
• WeChat OAuth login
• web-sdk/captcha_and_rate_limits.md – when captchas are triggered, how to integrate the captcha adapter + UI, and how to handle errors.
• web-sdk/web_best_practices.md – avoiding redundant logins, login-state persistence, and common UX patterns.

3. Node SDK & custom login

• node-sdk/node_overview_and_user_info.md – using the Node SDK to get user info, end-user info, query users, and read client IP.
• node-sdk/node_custom_login_ticket.md – issuing custom login tickets on the server and integrating with your own user system.

4. HTTP APIs

• http-api/http_overview.md – the HTTP API surface for auth and how to discover endpoints.
• http-api/http_login_and_token_flows.md – high-level flows for sign-in, sign-up, anonymous login, token grant/refresh/revoke, and user operations over HTTP.

5. Troubleshooting & FAQ

• troubleshooting/faq.md – common questions and pitfalls: anonymous vs unauthenticated, token expiry, verification limits, etc.

How to use this skill

When working on a CloudBase auth task, follow this sequence:

1. Clarify the scenario

• Is this frontend Web, Node backend/cloud function, or a generic backend calling HTTP APIs?
• What login methods are required (e.g. phone, email, WeChat, custom SSO, anonymous trial)?
• Are there existing users/identity systems that must be integrated?

2. Load only the relevant conceptual context

• For high-level decisions, read:
• concepts/overview.md
• concepts/login_methods.md
• concepts/user_accounts_and_roles.md
• Read concepts/tokens_and_sessions.md only if token behavior or migration is important to the task.

3. Jump to the relevant implementation section

• For Web implementation details, read web-sdk/web_quickstart.md and then the specific flow file (e.g. web-sdk/web_login_flows.md, web-sdk/captcha_and_rate_limits.md).
• For Node/server logic or custom login ticket issuance, use the node-sdk/ files.
• For language-agnostic HTTP integration, use the http-api/ files.

4. Design first, then code

• Use the conceptual files to pick login methods, user types, and token strategy.
• Then use Web/Node/HTTP sections to implement and verify the flow end-to-end.

5. Use troubleshooting only when needed

• Only read troubleshooting/faq.md when the user has issues like “anonymous vs not logged in”, unexpected expiration, or captcha errors.

Keep this file short in context. Load deeper files selectively based on the user’s question to keep the context window efficient.

Login methods in CloudBase Auth v2

This file summarizes the login methods and when to use them.

Anonymous login

What it is

• The SDK creates an anonymous user with a stable uid on the device.
• The user can access CloudBase resources according to your security rules.

Typical use cases

• Guest users trying a product without registration.
• Games or apps where you want to store personal progress before sign-up.

Key points

• One anonymous user per device; it never expires logically, but clearing local data may drop it.
• You can later upgrade an anonymous user to a formal user (see below).

Username/password login

What it is

• User logs in with a username and password.
• username can be:
• Phone number
• Email
• Custom username

Key points

• Direct sign-up via “username + password” alone is not allowed.
• Users are usually registered via SMS/email verification, then a username is bound.
• This reduces spam/abuse from arbitrary username registrations.

SMS verification code login

What it is

• User logs in with phone number + SMS code.

Key points

• Requires enabling SMS login and configuring SMS sending.
• Flow typically:

1. Send verification code to phone. 2. Verify code. 3. Login or sign-up depending on whether the user exists.

• Subject to per-number frequency limits (e.g. 30 seconds between sends, daily quotas).

Email verification code login

What it is

• User logs in with email + one-time email code.

Key points

• Requires enabling email login and setting up SMTP (sender, host, port, security mode).
• Similar flow to SMS:

1. Send verification to email. 2. Verify code. 3. Login or sign-up.

WeChat login

What it is

• Login via WeChat Open Platform.
• Users authorize via WeChat; CloudBase creates or reuses a corresponding user.

Key points

• You must configure WeChat app ID/secret in the CloudBase console.
• The Web SDK helps generate the WeChat OAuth URL and exchange authorization code for a provider token.
• Subsequent calls use a CloudBase token, not the raw WeChat token.

Custom login

What it is

• You already have your own identity system and want to map your user IDs to CloudBase users.
• Your backend/Cloud Function issues custom login tickets signed with a private key.

Key points

• Steps:

1. Download CloudBase custom login private key from the console. 2. Use Node SDK (or HTTP API) to issue tickets for your users. 3. The client uses the ticket to log into CloudBase.

• CloudBase creates a CloudBase user on first login and keeps the mapping to your customUserId.

Anonymous → formal user upgrade

Regardless of the initial login method, you can:

• Let users start anonymously.
• Later, when they provide phone/email/username, upgrade that anonymous account:
• Data created while anonymous is preserved and associated with the new formal identity.

This pattern is critical for:

• Reducing friction at first use.
• Avoiding data loss when users decide to register.

CloudBase Auth v2 overview

CloudBase Auth v2 is the identity layer for CloudBase. It provides:

• A unified user account system with a stable uid per user
• Multiple login methods (anonymous, username/password, SMS, email, WeChat, custom login)
• Token-based authentication using JWT access_token and long-lived refresh_token
• Tight integration with database, storage, and security rules

From the console perspective, you configure auth in 云开发控制台 → 身份认证 where you can:

• Open or close login methods
• View and manage users
• Inspect login records and basic behavior

From the app perspective:

• Every request from a logged-in user carries an auth token.
• CloudBase validates the token and enforces permissions before executing operations.

Supported login methods

Auth v2 supports:

• Anonymous login – frictionless trial, no registration; the user still has a stable uid on one device.
• Username/password login – traditional credentials; username can be phone, email, or a custom username.
• SMS code login – phone number + verification code.
• Email code login – email + verification code.
• WeChat login – via WeChat Open Platform for web/mobile apps.
• Custom login – you issue a ticket from your own identity system; CloudBase trusts and maps it to a CloudBase user.

Each method ultimately produces the same kind of CloudBase user and token set. The main differences are in:

• UX and friction
• Regulation/verification requirements (e.g. phone or email ownership)
• How you bootstrap the user into your product

Details per login method are summarized in concepts/login_methods.md.

Tokens, sessions, and v1 vs v2 differences

CloudBase Auth v2 uses a dual token model:

• Short-lived access token (access_token)
• Long-lived refresh token (refresh_token)

The Web/Node SDKs automatically manage these tokens for you; HTTP integrations need to manage them explicitly.

Access token (v2)

• Format: standard JWT.
• Encryption/signature: asymmetric (e.g. ES256 / RS256 style).
• Public keys:
• Exposed via https://{{EnvID}}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/certs
• Replace {{EnvID}} with your actual environment ID.
• Supports distributed verification:
• Any service with the public key can verify tokens without talking back to CloudBase.

Typical properties:

• Short lifetime (e.g. ~2 hours).
• Used as the bearer token to call CloudBase services.

Refresh token

Refresh tokens:

• Are long-lived (e.g. ~30 days).
• Are used to get new access tokens.
• Are usually stored and rotated by the SDK.

Important behaviors:

• As long as the refresh token is valid, the SDK can silently refresh the access token.
• For anonymous users, refresh tokens can auto-renew to preserve long-term anonymous sessions.

v1 vs v2 access tokens (for migration)

Key differences:

• Format
• v2: standard JWT
• v1: non-standard JWT string (often with environment-specific suffixes)
• Signing
• v2: asymmetric; public keys rotate regularly
• v1: symmetric per-environment key
• Verification
• v2: supports distributed verification through public keys
• v1: typically verified only by CloudBase itself

When building new systems, prefer v2. For migration:

• Be aware that token parsing and validation code must be updated.
• If you previously depended on v1’s specific string format, refactor to treat v2 as a standard JWT.

Validating v2 access tokens in your backend

For backends that need to trust CloudBase tokens directly:

1. Choose a JWT library for your language (see jwt.io). 2. Fetch CloudBase public keys:

• https://{{EnvID}}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/certs

3. Configure your verifier with:

• The key set
• Expected issuer (iss)
• Expected audience (aud)

4. Verify:

• Signature is valid
• Token is not expired
• Claims such as user_id, user_type, project_id meet your expectations

If signature and validity checks pass, you can trust the token as representing a CloudBase user.

Login state persistence (Web SDK)

In the Web SDK v2:

• Only local storage mode is supported for login state.
• This means:
• Login state persists across browser reloads.
• It persists until the user explicitly signs out or you clear local data.

Implications:

• UX is smoother (fewer forced re-logins).
• You should check for existing login state on app startup to avoid redundant sign-in flows.

User accounts, types, and roles

CloudBase Auth distinguishes several user types, all backed by a unified account system with a stable uid.

User types

• Internal users
• Have a fixed “internal user” role.
• Count toward plan limits (see billing docs).
• Typically used for administrators, operators, internal staff.

• External registered users
• Have a default “external user” role.
• No hard limit on user count (subject to plan).
• Represent your normal end-users/customers.

• Anonymous users
• Have a default “guest/visitor” role.
• Existence and behavior depend on your security rules.
• Identity is stored per device; CloudBase does not persist full profile like for registered users.

UIDs and identifiers

Each user has:

• A globally unique `uid`:
• Stable across the user’s lifetime.
• Consistent across platforms (web, mobile, backend).
• Optional identifiers:
• Phone number
• Email
• Username
• Third-party identifiers (e.g. WeChat Open Platform ID)
• customUserId for custom login

All of these map to one CloudBase user where desired.

Multi-account linking

CloudBase supports linking multiple login methods to a single user:

• Example:
• One user has:
• A phone number (SMS login)
• An email address (email login)
• A WeChat account
• All of these logins resolve to the same `uid`.

Benefits:

• Users can log in with whichever method is convenient.
• Data stays consistent regardless of login method.
• You can gradually add more login methods over time.

User data and permissions

With a CloudBase user:

• You can store private data in database and storage.
• You can write security rules referencing the user identity (e.g. uid == request.auth.uid).
• Anonymous users can still have private data, subject to:
• Device-based persistence
• Your rules and product design

For day-to-day management:

• The console view at “身份认证 / 用户管理” lets you:
• Inspect users and their identifiers.
• See when and how they logged in.
• Manage or troubleshoot issues.

HTTP login and token flows

This file summarizes typical flows using the HTTP APIs:

• Sign-in and sign-up.
• Anonymous login.
• Token grant/refresh/revoke.
• Basic user operations.

All endpoints use the base URL pattern:

• https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/...

1. Sign-in with username/password or phone/email

Use the 登录认证 endpoint (e.g. auth-sign-in):

Typical request (simplified Bash-style):

export env="your-env-id"
export deviceID="demo_device_5dh6nf"
export requestID="uuid-32-chars"

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/signin" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"username": "test@example.com", "password": "your password"}'

Response:

• Typically includes access_token, refresh_token, and user info.

2. Sign-up with SMS/email verification

Flow:

1. Send verification – verification endpoint:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/verification" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"phone_number": "+86 13800000000"}'

2. Verify code – verification/verify endpoint:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/verification/verify" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{"verification_code":"000000","verification_id":"verification_id"}'

3. Sign up – signup endpoint:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/signup" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{
    "phone_number":"+86 13800000000",
    "verification_code":"000000",
    "verification_token":"token-from-verify",
    "name":"手机用户",
    "password":"password",
    "username":"username"
  }'

3. Anonymous login

Use auth-sign-in-anonymously:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/signin-anonymously" \
  -X POST \
  -H "x-device-id: ${deviceID}" \
  -H "x-request-id: ${requestID}" \
  -u "${clientId}:${clientSecret}" \
  --data-raw '{}'

Response:

• Includes tokens describing an anonymous user.

Later, you can upgrade this user via sign-up with the anonymous token, similar to the Web flow.

4. Token grant, refresh, and revoke

Get or refresh CloudBase token (auth-grant-token)

Use when:

• Exchanging a refresh token for a new access token.
• Migrating between client credentials and end-user tokens.

Endpoint:

• POST /auth/v1/token (see auth-grant-token.api.mdx).

Revoke token (auth-revoke)

Use to invalidate a token:

• e.g. on logout or security events.

Endpoint:

• POST /auth/v1/revoke.

Introspect token (auth-token-introspect)

Use to validate token status:

• GET /auth/v1/token/introspect?token=...

Returns claims and validity information.

5. Basic user operations

Using the 用户管理 endpoints:

• user-me – get current user:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/user/me" \
  -H "Authorization: Bearer ${accessToken}"

• user-update-password – change password:

curl "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/user/password" \
  -X PATCH \
  -H "Authorization: Bearer ${accessToken}" \
  --data-raw '{"old_password":"old","new_password":"new"}'

• user-edit-user-basic-info – update profile fields.
• user-delete-me – delete current user.
• user-providers / bind / unbind – manage linked third-party providers.

Refer to the specific .api.mdx files for full request/response schemas.

HTTP API overview for CloudBase Auth

This file summarizes the HTTP API docs:

• 登录认证接口.info.mdx
• sidebar.js for auth-related routes.

When to use HTTP APIs

Use HTTP auth APIs when:

• You are integrating from non-Node backends or services.
• You want to call auth from scripts (e.g. Bash, Python).
• You need fine-grained control over tokens and flows.

The HTTP APIs generally mirror the capabilities of:

• Web SDK (auth.signIn, auth.signUp, etc.).
• Node SDK (tokens, user info, etc.).

API categories (from sidebar)

1. 登录认证

• auth-sign-in – sign in (username/password, phone, email, verification).
• auth-sign-in-anonymously – anonymous login.
• auth-sign-up – sign up.
• auth-reset-password – reset password.
• auth-sign-out – sign out.
• auth-client-credential – get service-side token via client credentials.

2. 第三方登录认证

• auth-gen-provider-redirect-uri – get third-party auth redirect URL.
• auth-grant-provider-token – exchange code for provider token.
• auth-sign-in-with-provider – sign in with provider token.
• 自定义登录 – custom login via HTTP.

3. token管理

• auth-grant-token – get or refresh CloudBase token.
• auth-revoke – revoke token.
• auth-token-introspect – introspect/validate token.

4. 用户管理

• user-sudo – obtain temporary sudo token.
• user-me – get current user info.
• user-delete-me – delete current user.
• user-update-password – change password.
• user-edit-user-basic-info – update basic profile.
• user-bind-with-provider – bind third-party account.
• user-un-bind-provider – unbind third-party account.
• user-providers – list bound providers.

5. 验证码

• 获取图片验证码 – get picture captcha.
• 验证图片验证码 – verify picture captcha.
• 发送短信、邮箱验证码 – send SMS/email verification code.
• 验证短信、邮箱验证码 – verify SMS/email verification code.

Base URL and common headers

From examples in the docs:

• Base URL pattern:
• https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/...
• Common headers:
• x-device-id – identify device (for some flows).
• x-request-id – unique request ID for tracing.
• Authorization or basic auth (-u clientId:clientSecret) depending on endpoint.

Where to go next

• Use http-api/http_login_and_token_flows.md for concrete flows:
• Sign-in/sign-up over HTTP.
• Anonymous login.
• Token grant/refresh/revoke.
• Simple user operations.

Node SDK custom login ticket issuance

This file explains how to implement the custom login flow with the Node SDK, using the createTicket API and the client-side custom ticket login.

When to use custom login

Use custom login when:

• You already have your own user system (e.g. existing accounts in another service).
• You want each of your users to map to a CloudBase user without forcing them to re-register.
• You want to centralize authentication logic on your own backend.

Conceptually:

• Your backend creates a signed ticket for a given customUserId.
• The client uses that ticket to log into CloudBase.

Step 1: Get custom login private key

In the console:

1. Go to 身份认证 → 登录方式. 2. Enable 自定义登录. 3. Download the custom login private key file (JSON). 4. Deploy this file securely to your server or Cloud Function, e.g. /path/to/your/tcb_custom_login.json.

Security notes:

• Treat this file like a secret.
• Rotating the key will invalidate previous keys after a grace period.

Step 2: Issue tickets with Node SDK

Example Node code:

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

// 1. Initialize with custom login credentials
const app = cloudbase.init({
  env: "your-env-id",
  credentials: require("/path/to/your/tcb_custom_login.json"),
});

const auth = app.auth();

// 2. Your own user ID
const customUserId = "your-customUserId";

// 3. Create ticket
const ticket = auth.createTicket(customUserId, {
  // optional:
  refresh: 3600 * 1000, // refresh interval
  expire: 24 * 3600 * 1000, // ticket expiration
});

// 4. Return ticket to the client (e.g. via HTTP response)
return ticket;

Constraints for customUserId (from docs):

• 4–32 characters.
• Characters: letters, digits, and _-#@(){}[]:.,<>+#~.

Step 3: Client-side custom login

On the client (Web SDK):

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

const app = cloudbase.init({ env: "your-env-id" });
const auth = app.auth();

async function loginWithCustomTicket() {
  const loginState = auth.hasLoginState();
  if (!loginState) {
    // 1. Configure how to fetch ticket from your backend
    await auth.setCustomSignFunc(async () => {
      const ticket = "fetch-ticket-from-backend"; // e.g. via fetch()
      return ticket;
    });

    // 2. Sign in with custom ticket
    await auth.signInWithCustomTicket();
  }
}

End-to-end flow summary

1. Your user authenticates with your own system. 2. Your backend (Node SDK) calls createTicket(customUserId, options) and returns the ticket. 3. Client calls setCustomSignFunc to obtain the ticket and signInWithCustomTicket. 4. CloudBase verifies the ticket, creates or reuses a CloudBase user mapped to customUserId.

This flow decouples your identity system from CloudBase while still giving full access to CloudBase Auth and user-linked resources.

Node SDK auth overview and user info

This file summarizes the key Node SDK auth capabilities:

• Getting user info in cloud functions / Node services.
• Querying end-user info by UID or login identifier.
• Reading client IP.

Basic initialization

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({ env: "your-env-id" });
const auth = app.auth();

getUserInfo (cloud function context)

Use when your code runs inside a CloudBase Node function and you need the current caller’s IDs:

exports.main = async (event, context) => {
  const { openId, appId, uid, customUserId } = auth.getUserInfo();

  console.log(openId, appId, uid, customUserId);
};

Fields:

• openId / appId – WeChat-related identifiers (if applicable).
• uid – CloudBase user ID.
• customUserId – developer-defined ID, used with custom login.

getEndUserInfo

Use when you want full CloudBase end-user profile:

const { userInfo, requestId } = await auth.getEndUserInfo("user-uid");

userInfo typically includes:

• openId, appId, uid, customUserId, envName
• nickName, email, username, hasPassword
• Location (country, province, city)
• avatarUrl, qqMiniOpenId, etc.

If you omit uid, the method can also read from environment variables (depending on context).

queryUserInfo

Use when you need to find a user by login identifier:

const { userInfo } = await auth.queryUserInfo({
  platform: "PHONE" | "USERNAME" | "EMAIL" | "CUSTOM",
  platformId: "login-identifier",
  // uid optional; if provided, it takes precedence.
});

Examples:

• Find by phone:

await auth.queryUserInfo({
  platform: "PHONE",
  platformId: "+86 13800000000",
});

• Find by customUserId:

await auth.queryUserInfo({
  platform: "CUSTOM",
  platformId: "your-customUserId",
});

getClientIP

When running inside a Node function and you need the caller IP:

const ip = auth.getClientIP();
console.log(ip);

When to use Node SDK vs HTTP API

• Prefer Node SDK when:
• Running inside CloudBase functions or Node services.
• You want higher-level helpers for user lookup.
• Prefer HTTP APIs when:
• Using non-Node languages.
• Integrating with external systems that cannot easily use Node SDK.

Auth FAQ and troubleshooting

This file provides answers to common CloudBase Auth questions and troubleshooting guidance.

Q1: What’s the difference between anonymous login and “not logged in”?

From the user’s perspective:

• Both feel like “no registration required”.
• With anonymous login, the user still has a persistent identity on the same device.

From the developer’s perspective:

• Anonymous login:
• Creates a valid CloudBase user with a uid.
• You can store private database/storage data tied to that uid.
• You can use security rules to control their access.
• Not logged in:
• No user identity; requests do not have a uid.
• Cannot access most CloudBase services under default rules.

Q2: Do anonymous users expire?

• CloudBase’s policy:
• Each device has at most one anonymous user at a time.
• The anonymous user does not have a fixed expiry in CloudBase.
• However:
• If the user clears local data or reinstalls the app, the local identity may be lost.
• A new anonymous user may be created on next login.

Design implication:

• Plan for data continuity via anonymous → registered upgrade flows.

Q3: Why do I keep seeing captchas or rate-limit errors?

Possible causes:

• Too many failed login attempts (e.g. password wrong too often).
• Too many SMS/email verification sends for the same number/email in a short window.

Mitigations:

• Implement the full captcha flow (web-sdk/captcha_and_rate_limits.md).
• Respect frequency limits and add client-side constraints.
• Show user-friendly errors and suggest waiting before retrying.

Q4: Why does my user seem logged out unexpectedly?

Check:

• Is the app using Web SDK v2 with local storage for login state?
• Did the user:
• Clear browser storage/cookies?
• Switch devices or browsers?

Also:

• Access tokens are short-lived; if your backend uses them directly, make sure you:
• Refresh them via refresh tokens or SDK.
• Handle token expiry gracefully by re-authenticating.

Q5: How do I debug token-related issues?

Steps:

1. Decode the JWT (for v2) using any JWT debugger (e.g. jwt.io) to inspect claims. 2. Verify:

• iss, aud, and exp fields.

3. Use the introspection HTTP API (auth-token-introspect) if needed. 4. Ensure you:

• Use the correct environment ID for public keys.
• Have not mixed tokens between environments.

Q6: When should I use custom login vs built-in login methods?

Use built-in methods when:

• You are starting from scratch and do not have an existing identity system.
• You want CloudBase to handle user credentials/storage.

Use custom login when:

• You already manage users elsewhere (SSO, legacy user DB).
• CloudBase should reference those users without duplicating credentials.

Captcha handling and rate limits (Web SDK)

This file explains how captcha challenges and related rate limits work in CloudBase Auth v2 and how to integrate them with the Web SDK.

When captchas are required

Captcha challenges may be triggered when:

• Username/password login fails repeatedly (e.g. 5 times).
• Sending SMS or email verification codes reaches rate limits.

Typical error codes:

• error == "captcha_required" – captcha is required for the request.
• error == "captcha_invalid" – captcha is invalid or expired; you must fetch a new one.

High-level captcha flow

1. User performs an action (login or send code). 2. Backend returns an error indicating captcha is required. 3. The SDK adapter’s openURIWithCallback is called with a captcha URL. 4. You parse the URL and extract:

• captchaData – image (Base64)
• state – captcha state identifier
• token – captcha token

5. You show the captcha to the user, collect their input, and call auth.verifyCaptchaData. 6. You signal the adapter that captcha was solved so it can retry the original operation.

Example adapter structure

Pseudo-code (adapted from the official guide):

function genAdapter(options) {
  const adapter: SDKAdapterInterface = {
    captchaOptions: {
      openURIWithCallback: async (url: string) => {
        // 1. Parse captcha data from URL
        const { captchaData, state, token } = cloudbase.parseCaptcha(url);

        // 2. Notify your UI via an event bus
        options.EVENT_BUS.emit("CAPTCHA_DATA_CHANGE", {
          captchaData, // Base64 image
          state,
          token,
        });

        // 3. Wait for captcha verification result
        return new Promise((resolve) => {
          options.EVENT_BUS.once("RESOLVE_CAPTCHA_DATA", (res) => {
            // res is result of auth.verifyCaptchaData
            resolve(res);
          });
        });
      },
    },
  };
  return adapter;
}

Wiring the adapter into the SDK

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

const EVENT_BUS = new EventBus();
const adapter = genAdapter({ EVENT_BUS });

cloudbase.useAdapters(adapter, { EVENT_BUS });

const app = cloudbase.init({
  env: "your-env-id",
  appSign: "app-id",
  appSecret: {
    appAccessKeyId: "version",
    appAccessKey: "secret",
  },
});

const auth = app.auth();

UI-side handling

• Listen for captcha data:

let captchaState = {
  captchaData: "",
  state: "",
  token: "",
};

EVENT_BUS.on("CAPTCHA_DATA_CHANGE", ({ captchaData, state, token }) => {
  captchaState = { captchaData, state, token };
  // display captcha image in UI, e.g. <img src={captchaData} />
});

• Refresh captcha:

async function refreshCaptcha() {
  const result = await auth.createCaptchaData({ state: captchaState.state });
  captchaState = {
    ...captchaState,
    captchaData: result.data,
    token: result.token,
  };
}

• Verify captcha:

async function verifyCaptchaData(userInput: string) {
  const verifyResult = await auth.verifyCaptchaData({
    token: captchaState.token,
    key: userInput,
  });

  EVENT_BUS.emit("RESOLVE_CAPTCHA_DATA", verifyResult);
}

Best practices

• Treat captcha_required as “show captcha if not already shown”.
• Treat captcha_invalid as “refresh captcha and ask user again”; avoid infinite loops.
• Add a user-friendly UI and retry logic for the original operation after captcha succeeds.

Web auth best practices

This file summarizes the “最佳实践” and related guidance for Web:

• Avoid unnecessary logins.
• Use persistent login state correctly.
• Provide a smooth UX around auth.

1. Avoid redundant login calls

On app startup:

const auth = app.auth();

if (auth.hasLoginState()) {
  // Already logged in; do NOT start a new login flow.
  // You can safely use auth.currentUser and tokens.
} else {
  // Not logged in or login state has expired; start your login flow.
}

Benefits:

• Fewer unnecessary network calls.
• Avoids confusing behavior (e.g. prompts for code/password when already logged in).

2. Understand login-state persistence

In Web SDK v2:

• Only local storage is supported for login state.
• This means:
• Login survives page reloads and browser restarts (unless storage is cleared).
• Users do not need to log in every visit.

Implications for UX:

• Prefer showing the app directly if hasLoginState() is true.
• Provide a clear “Sign out” action that calls auth.signOut().

3. Keep security rules aligned with auth

Auth alone does not secure data; you must align:

• Authentication (who the user is).
• Authorization (what they can access) via:
• Database security rules.
• Storage security rules.
• Backend logic.

Patterns:

• Use uid and other identity info in rules.
• Ensure anonymous users have limited access (e.g. read-only or scoped data).
• Elevate permissions for internal users or admins explicitly, not implicitly.

4. Think about anonymous → registered journeys

Good patterns:

• Let users explore anonymously with limited capabilities.
• At key moments (e.g. saving progress, sharing content), prompt for registration.
• Use the anonymous upgrade flow so that existing data is preserved when they register.

5. Handle rate limits and captchas gracefully

• Expect captcha challenges when:
• Login attempts fail repeatedly.
• Verification sending hits limits.
• Provide a dedicated captcha UI and clear error messages.
• Avoid infinite retries; if captcha fails repeatedly, surface an error and suggest waiting or contacting support.

Web login flows

This file provides complete Web SDK login flows for all supported CloudBase Auth methods.

Each flow assumes you have:

• const app = cloudbase.init({ env: "your-env-id" });
• const auth = app.auth();

1. Register with SMS or email verification, then log in

Send SMS verification code

const phoneNumber = "+86 13800000000"; // include country code

const verification = await auth.getVerification({
  phone_number: phoneNumber,
});

Send email verification code

const email = "test@example.com";

const verification = await auth.getVerification({
  email,
});

Verify code and sign up or sign in

// User-entered code
const verificationCode = "000000";

// 1. Verify code
const verificationTokenRes = await auth.verify({
  verification_id: verification.verification_id,
  verification_code: verificationCode,
});

// 2. Register or sign in
if (verification.is_user) {
  // Existing user: sign in
  await auth.signIn({
    username: phoneNumber, // or email
    verification_token: verificationTokenRes.verification_token,
  });
} else {
  // New user: sign up (this also logs in)
  await auth.signUp({
    phone_number: phoneNumber,
    verification_code: verificationCode,
    verification_token: verificationTokenRes.verification_token,
    // optional
    name: "手机用户",
    password: "password",
    username: "username",
  });
}

2. Username/password login

Assumes the user has already been registered via verification and has a username/phone/email bound.

const loginState = await auth.signIn({
  username: "your username", // phone, email, or username
  password: "your password",
});

3. SMS code login (one-step login)

const phoneNum = "13800000000";

// 1. Send SMS code
const verificationInfo = await auth.getVerification({
  phone_number: `+86 ${phoneNum}`,
});

// 2. User fills in code
const verificationCode = "000000";

// 3. Sign in with SMS
await auth.signInWithSms({
  verificationInfo,
  verificationCode,
  phoneNum,
});

4. Email code login

const email = "test@example.com";

// 1. Send email code
const verificationInfo = await auth.getVerification({ email });

// 2. User fills in code
const verificationCode = "000000";

// 3. Sign in with email code
await auth.signInWithEmail({
  verificationInfo,
  verificationCode,
  email,
});

5. Anonymous login and upgrade

Anonymous login

await auth.signInAnonymously();
const loginScope = await auth.loginScope();
console.log(loginScope === "anonymous"); // true if anonymous

Upgrade anonymous user to formal account

// 1. Anonymous login
await auth.signInAnonymously();

// 2. Get access token for the anonymous session
const { accessToken } = await auth.getAccessToken();

// 3. Register a formal user linked to this anonymous account
await auth.signUp({
  // other signup params (e.g. phone_number, verification_code, etc.)
  anonymous_token: accessToken,
});

6. WeChat login (Web, via WeChat Open Platform)

Step 1: Generate provider redirect URI

const { uri } = await auth.genProviderRedirectUri({
  provider_id: "wx_open",          // WeChat Open Platform
  provider_redirect_uri: "...",    // your redirect URI
  state: "some_state",             // CSRF/state marker
  other_params: {},                // optional
});

// Redirect user to this URI for authorization
location.href = uri;

Step 2: Handle callback, get provider token

In your redirect handler:

// From URL params
const provider_code = "code_from_query";

const { provider_token } = await auth.grantProviderToken({
  provider_id: "wx_open",
  provider_redirect_uri: "curpage", // URL the user was sent back to
  provider_code,
});

Step 3: Sign in with provider token

await auth.signInWithProvider({
  provider_token,
});

Web SDK quickstart for CloudBase Auth v2

This section summarizes how to use the Web SDK for authentication.

Install and initialize the SDK

npm install --save @cloudbase/js-sdk

Basic initialization:

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

const app = cloudbase.init({
  env: "your-env-id",
});

const auth = app.auth();

For web apps:

• Ensure your domain is added to the 安全来源列表 in the console (安全域名).
• Otherwise, requests may be treated as invalid origin.

Opening login methods

Before calling login APIs, ensure the corresponding methods are enabled:

• Go to 云开发控制台 → 身份认证 → 登录方式.
• Enable:
• 匿名登录
• 短信验证码登录
• 邮箱验证码登录
• 用户名密码登录
• 微信开放平台登录
• 自定义登录

as needed.

Alternatively, you can manage login methods programmatically via Tencent Cloud SDKs:

• Use the EditAuthConfig API with parameters like PhoneNumberLogin, AnonymousLogin, UsernameLogin set to TRUE or FALSE.
• This is useful for infrastructure-as-code or automated environment setup.
• For most manual configuration, the console UI is simpler.

Basic sign-in and sign-out

Sign in with username/password

const loginState = await auth.signIn({
  username: "your username", // phone, email, or username
  password: "your password",
});

Sign out

await auth.signOut();

Getting the current user

const app = cloudbase.init({ env: "your-env-id" });
const auth = app.auth();

// After you log in...
const user = auth.currentUser;       // sync
// or:
// const user = await auth.getCurrentUser(); // async

if (user) {
  const uid = user.uid;
  const name = user.name;
}

You can also update and refresh user profile fields using the User object and its methods (e.g. update, refresh), as exposed by the Web SDK.

Where to go next

For specific flows, use:

• web-sdk/web_login_flows.md for detailed patterns (SMS, email, anonymous, WeChat, username/password).
• web-sdk/captcha_and_rate_limits.md for integrating captchas.
• web-sdk/web_best_practices.md for handling login state and avoiding redundant logins.