身份认证（旧版）

提示

当前@cloudbase/js-sdk 版本已推出 v3 next 版本。若需使用 v3 next 版本，请参考v3 next 文档；若需使用 v1 版本，请参考v1 文档

App.auth()

接口描述

返回 Auth 对象，身份认证相关的属性和方法都在 Auth 对象中

接口声明：auth(): Auth

信息

@cloudbase/js-sdk@2.x 版本将只支持 local 方式（Web 端在显式退出登录之前 30 天保留身份验证状态）存储身份状态。（原 1.x 版本的 session 及 none 模式不再支持）

示例代码

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

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

注册/登录/登出相关

提示

手机号验证码注册 仅支持 上海 地域

Auth.signUp()

接口描述

接口功能：注册用户，目前支持手机号验证码注册，邮箱验证码注册。更多详细流程可参考用户注册。

接口声明：signUp(params: SignUpRequest): Promise<LoginState>

接口入参: SignUpRequest

字段	类型	必填	说明
phone_number	string	否	注册所用手机号，phone_number 与 email 必须任选其一使用
email	string	否	注册所用邮箱 ，phone_number 与 email 必须任选其一使用
verification_code	string	否	验证码，可通过Auth.getVerification获取
verification_token	string	否	验证码 token，可通过Auth.verify获取
provider_token	string	否	第三方 provider token，用于绑定第三方用户信息，可通过Auth.grantProviderToken获取
password	string	否	密码
name	string	否	用户名
gender	string	否	性别
picture	string	否	头像
locale	string	否	地址
username	string	否	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文

接口出参: LoginState

详见 LoginState

示例代码

// 初始化SDK
const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 例：手机号验证码注册

// 第一步：用户点击获取验证码，调用如下方法发送短信验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const phoneNumber = "+86 13800000000";
const verification = await auth.getVerification({
  phone_number: phoneNumber,
});

// 若使用邮箱验证，第一步代码改为
{
  const email = "test@example.com";
  const verification = await auth.getVerification({
    email: email,
  });
}

// 验证码验证
// 调用发送短信接口后，手机将会收到云开发的短信验证码。
// 用户填入短信验证码，可以调用下面的接口进行验证。

// 第二步：等待用户在页面中输入短信验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证短信验证码
const verificationTokenRes = await auth.verify({
  verification_id: verification.verification_id,
  verification_code: verificationCode,
});

// 第四步：注册
// 如果该用户已经存，则登录
if (verification.is_user) {
  await auth.signIn({
    username: phoneNumber,
    verification_token: verificationTokenRes.verification_token,
  });
} else {
  // 否则，则注册新用户，注册新用户时，可以设置密码，用户名
  // 备注：signUp 成功后，会自动登录
  await auth.signUp({
    phone_number: phoneNumber,
    verification_code: verificationCode,
    verification_token: verificationTokenRes.verification_token,
    // 可选，设置昵称
    name: "手机用户",
    // 可选，设置密码
    password: "password",
    // 可选，设置登录用户名
    username: "username",
  });
}

Auth.signIn()

提示

手机号登录 仅支持 上海 地域

接口描述

接口功能：在已完成注册后，可通过该方法进行用户登录，目前支持手机号，邮箱，用户名密码登录。用户名密码登录的详细流程可参考账号密码登录。

接口声明：signIn(params: SignInRequest): Promise<LoginState>

接口入参: SignInRequest

字段	类型	必填	说明
username	string	是	用户手机号，邮箱或自定义用户名，如果是中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”
password	string	否	用户密码 ，password 与 verification_token 必须任选其一
verification_token	string	否	验证码 token ，password 与 verification_token 必须任选其一，可通过Auth.verify获取

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 已完成注册
// 例：手机号登录
const phoneNumber = "+86 13800000000";

await auth.signIn({
  username: phoneNumber,
  password: "your password",
});

// 例：邮箱登录
const email = "test@example.com";

await auth.signIn({
  username: email,
  password: "your password",
});

// 例：用户名登录
const username = "myname";
await auth.signIn({
  username,
  password: "your password",
});

Auth.signOut()

接口描述

接口功能：退出登录

接口声明：signOut(params?: SignoutRequest): Promise<SignoutReponse>

接口入参: SignoutRequest

字段	类型	必填	说明
redirect_uri	string	否	退出后的重定向页面地址
state	string	否	在有 redirect_uri 时，会将该参数放在 redirect_uri 的链接参数 state 中，用于区分某个身份源

接口出参: SignoutReponse

字段	类型	说明
redirect_uri	string	重定向页面地址，如果入参传了 redirect_uri 或第三方认证源配置了 redirect_uri，则会有返回

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 监听登录态变化
auth.onLoginStateChanged((params) => {
  console.log(params);
  const { eventType } = params?.data || {};
  switch (eventType) {
    case "sign_in":
      // 登录成功
      break;
    case "sign_out":
      // 退出登录成功
      break;
    case "credentials_error":
      // 权限失效
      break;
    default:
      return;
  }
});

await auth.signOut();

Auth.signInAnonymously()

接口描述

接口功能：匿名登录，详细流程可参考匿名登录。

接口声明 signInAnonymously(): Promise<LoginState>

接口入参: 无

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
await auth.signInAnonymously();

Auth.setCustomSignFunc()

接口描述

接口功能：设置获取自定义登录 ticket 函数

接口声明：setCustomSignFunc(getTickFn: GetCustomSignTicketFn): void

接口入参: GetCustomSignTicketFn

字段	类型	说明
getTickFn	() => Promise<string>	获取自定义登录 ticket 的函数

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});
const auth = app.auth();
const getTickFn = new Promise((resolve, reject));
await auth.setCustomSignFunc(getTickFn);

Auth.signInWithCustomTicket()

接口描述

接口功能：自定义登录，配合Auth.setCustomSignFunc使用。详细流程可参考自定义登录。

接口声明：signInWithCustomTicket(): Promise<LoginState>

接口入参: 无

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
await auth.signInWithCustomTicket();

Auth.signInWithOpenId()

提示

仅支持在 微信小程序 中使用

接口描述

接口功能：微信小程序 openId 静默登录。如果用户不存在，会根据云开发平台-登录方式中对应身份源的登录模式配置，判断是否自动注册

接口声明：signInWithOpenId(params?: SignInWithOpenIdReq): Promise<LoginState>

接口入参: SignInWithOpenIdReq

字段	类型	必填	默认值	说明
useWxCloud	boolean	否	true	true： 使用微信云开发模式进行请求，需开通小程序微信云开发环境； false：使用普通 http 请求

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
await auth.signInWithOpenId();

Auth.signInWithUnionId()

提示

仅支持在 微信小程序 中使用

接口描述

接口功能：微信小程序 unionId 静默登录。如果用户不存在，会根据云开发平台-登录方式中对应身份源的登录模式配置，判断是否自动注册

接口声明：signInWithUnionId(): Promise<LoginState>

接口入参: 无

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
await auth.signInWithUnionId();

Auth.signInWithPhoneAuth()

提示

仅支持在 微信小程序 中使用

接口描述

接口功能：微信小程序手机号授权登录。如果用户不存在，会根据云开发平台-登录方式中对应身份源的登录模式配置，判断是否自动注册

接口声明：signInWithPhoneAuth(params: SignInWithPhoneAuthReq): Promise<LoginState>

接口入参: SignInWithPhoneAuthReq

字段	类型	必填	默认值	说明
phoneCode	string	是	空	微信小程序手机号授权码，通过微信小程序手机号快速验证组件

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
await auth.signInWithPhoneAuth({ phoneCode: "xxx" });

Auth.signInWithSms()

提示

仅支持 上海 地域

接口描述

接口功能：短信验证码登陆。详细流程可参考短信验证码登录。

接口声明：signInWithSms(params: SignInWithSmsReq): Promise<LoginState>

接口入参: SignInWithSmsReq

字段	类型	必填	默认值	说明
verificationInfo	object	验证码 token 信息		Auth.getVerification的返回值
verificationCode	string	验证码	空	获取到的短信验证码，调用Auth.getVerification后会发送验证码
phoneNum	string	手机号	空	获取验证码的手机号，中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

const phoneNumber = "+86 13800000000";

// 第一步：用户点击获取验证码，调用如下方法发送短信验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const verificationInfo = await auth.getVerification({
  phone_number: phoneNumber,
});

// 第二步：等待用户在页面中输入短信验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证短信验证码，并登录
await auth.signInWithSms({
  verificationInfo,
  verificationCode, // 用户输入的短信验证码
  phoneNum: phoneNumber, // 用户手机号
});

Auth.signInWithEmail()

接口描述

接口功能：邮箱验证码登陆。详细流程可参考邮箱验证码登录。

接口声明：signInWithEmail(params: SignInWithEmailReq): Promise<LoginState>

接口入参: SignInWithEmailReq

字段	类型	必填	默认值	说明
verificationInfo	object	验证码 token 信息		Auth.getVerification的返回值
verificationCode	string	验证码	空	获取到的邮箱验证码，调用Auth.getVerification后会发送验证码
email	string	邮箱	空	获取验证码的邮箱地址

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

const email = "test@example.com";

// 第一步：用户点击获取验证码，调用如下方法发送邮箱验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const verificationInfo = await auth.getVerification({
  email: email,
});

// 第二步：等待用户在页面中输入邮箱验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证邮箱验证码，并登录
await auth.signInWithEmail({
  verificationInfo,
  verificationCode, // 用户输入的邮箱验证码
  email: email, // 用户邮箱
});

Auth.toDefaultLoginPage()

提示

使用此功能请升级 @cloudbase/js-sdk 至 2.18.0 及以后版本

接口描述

接口功能：跳转系统默认登录页，兼容 web 和微信小程序端

接口声明：toDefaultLoginPage(params: authModels.ToDefaultLoginPage): Promise<void>

接口入参: ToDefaultLoginPage

字段	类型	含义	默认值	说明
config_version	string	默认登录页面的登录配置版本	env	1、‘env’表示托管登录页配置，可在“云开发平台-身份认证”中设置，2、非‘env’表示使用独立的托管登录页配置，可在“云开发平台-可视化低代码-访问控制”中设置，相应的 config_version 可以在应用自动跳转的__auth 登录页面的链接中参数获取到
redirect_uri	string	登录后重定向地址	默认为当前页面地址
app_id	string	应用 id	空	config_version 不是‘env’的时候为必填项，如 app-xxx
query	object	跳转到默认登录页要携带的参数	空

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

await auth.toDefaultLoginPage({
  config_version: "env",
  app_id: "app-xxx",
  redirect_uri: "xxx",
});

本地调试

如果开发 Web 端应用，由于 __auth 登录页面静态资源存放于静态网站托管中，所以在本地调试时需要配置代理才能成功跳转 __auth 登录页面。

推荐使用 Whistle 工具进行代理配置。 __auth 登录页面的访问域名可在静态网站托管-配置信息-默认域名中查看。

假设本地启动应用的访问地址为 http://localhost:3000，__auth 登录页面的访问域名为lowcode-xxx-xxx.tcloudbaseapp.com，则 Whistle 代理的 Rules 配置如下：

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

# 应用其他路径代理配置

运行应用后，通过 https://lowcode-xxx-xxx.tcloudbaseapp.com 即可访问应用

第三方平台登录相关

Auth.genProviderRedirectUri()

接口描述

接口功能：生成第三方平台授权 Uri （如微信二维码扫码授权网页）

接口声明：genProviderRedirectUri(params: GenProviderRedirectUriRequest): Promise<GenProviderRedirectUriResponse>

接口入参: GenProviderRedirectUriRequest

字段	类型	必填	说明
provider_id	string	是	第三方平台 ID，参考系统内置三方平台列表
provider_redirect_uri	string	是	第三方平台重定向 Uri，授权完成后，重定向时会在 url 中携带 code 参数
state	string	是	用户自定义状态标识字段，识别三方平台回调来源
other_params	{sign_out_uri?:string}	否	其他参数

接口出参: GenProviderRedirectUriResponse

字段	类型	必填	说明
uri	string	是	客户端请求
signout_uri	string	是	登出 Uri

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
const providerId = "test_provider_id"; // 第三方平台 ID
const providerUri = "test_provider_redirect_uri"; // 第三方平台重定向 Uri
const state = "wx_open"; // 用户自定义状态标识字段
const otherParams = { sign_out_uri: "test_sign_out_uri" }; // 其他参数

// 三方平台授权登录示例

// 1. 获取第三方平台授权页地址（如微信授权）
const { uri } = await auth.genProviderRedirectUri({
  provider_id: providerId,
  provider_redirect_uri: providerUri,
  state: state,
  other_params: otherParams,
});

// 2. 访问uri （如 location.href = uri）

// 3. 授权 （如微信扫码授权）

// 4. 回调至 provider_redirect_uri 地址（url query中携带 授权code，state等参数），此时检查 state 是否符合预期（如 自己设置的 wx_open)
const provider_code = "your provider code";

// 5. state符合预期（微信开放平台授权 wx_open），则获取该三方平台token
const { provider_token } = await auth.grantProviderToken({
  provider_id: "wx_open",
  provider_redirect_uri: "cur page", // 指定三方平台跳回的 url 地址
  provider_code: provider_code, // 第三方平台跳转回页面时，url param 中携带的 code 参数
});

// 6. 通过 provider_token 仅登录或登录并注册（与云开发平台-登录方式-身份源登录模式配置有关）
await auth.signInWithProvider({
  provider_token,
});

Auth.grantProviderToken()

接口描述

接口功能：提供第三方平台登录 token

接口声明：grantProviderToken(params: GrantProviderTokenRequest): Promise<GrantProviderTokenResponse>

接口入参: GrantProviderTokenRequest

字段	类型	必填	说明
provider_id	string	是	第三方平台 ID，参考系统内置三方列表
provider_redirect_uri	string	否	第三方平台重定向 uri
provider_code	string	否	第三方平台授权 code（重定向 uri 中携带）
provider_access_token	string	否	第三方平台访问 token（重定向 uri 中携带）
provider_id_token	string	否	第三方平台 ID token（重定向 uri 中携带）

接口出参: GrantProviderTokenResponse

字段	类型	必填	说明
provider_token	string	是	第三方平台 token
expires_in	number	是	有效期
provider_profile	ProviderProfile	否	第三方身份源信息

ProviderProfile

字段	类型	必填	说明
provider_id	string	是	默认内置的三方 providerid，wx_open, wx_mp
sub	string	是	第三方用户 id (如 wxopenid)
name	string	否	名称
phone_number	string	否	手机号
picture	string	否	头像
meta	ProviderProfileMeta	否	第三方身份源扩展信息(小程序返回)

ProviderProfileMeta

字段	类型	必填	说明
appid	string	否	小程序的 appid
openid	string	否	小程序的 openid

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
const providerId = "wx_open"; // 微信开放平台
auth.grantProviderToken({
  provider_id: providerId,
  provider_redirect_uri: "cur page", // 指定三方平台跳回的 url 地址
  provider_code: "provider code", // 第三方平台跳转回页面时，url param 中携带的 code 参数
});

Auth.signInWithProvider()

接口描述

接口功能：第三方平台登录。如果用户不存在，会根据云开发平台-登录方式中对应身份源的登录模式配置，判断是否自动注册

接口声明：signInWithProvider(params: SignInWithProviderRequest): Promise<LoginState>

接口入参: SignInWithProviderRequest

字段	类型	必填	说明
provider_token	string	是	第三方平台 token，可通过Auth.grantProviderToken获取

接口出参: LoginState

详见 LoginState

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
const providerToken = "test_provider_token";
auth.signInWithProvider({
  provider_token: providerToken,
});

Auth.unbindProvider()

接口描述

接口功能：解除第三方绑定

接口声明：unbindProvider(params: UnbindProviderRequest): Promise<void>

接口入参: UnbindProviderRequest

字段	类型	必填	说明
provider_id	string	是	第三方平台 ID，参考第三方绑定时的回包，可通过Auth.getProviders获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 完成登录后

// 获取绑定第三方平台ID
const { id } = await auth.getProviders();

await auth.unbindProvider({
  provider_id: id,
});

Auth.getProviders()

接口描述

接口功能：获取第三方绑定列表

接口声明：getProviders(): Promise<UserProfileProvider>

接口入参: 无

接口出参: UserProfileProvider

字段	类型	必填	说明
id	string	是	第三方平台 ID
provider_user_id	string	是	第三方平台用户 ID
name	string	是	第三方平台昵称

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 完成登录后

await auth.getProviders();

Auth.bindWithProvider()

接口描述

接口功能：绑定第三方登录

接口声明：bindWithProvider(params: BindWithProviderRequest): Promise<void>

接口入参: BindWithProviderRequest

字段	类型	必填	说明
provider_token	string	是	第三方平台授权 token，可通过Auth.grantProviderToken 获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});
const provider_token = "test_provider_token"; // 参考Auth.grantProviderToken 获取

const auth = app.auth();
await auth.bindWithProvider({
  provider_token,
});

验证/授权相关

Auth.verifyCaptchaData()

接口描述

接口功能：验证图形验证码数据，用于自定义适配器或使用 adapter 时处理图形验证码验证流程

接口声明：verifyCaptchaData(params: VerifyCaptchaDataRequest): Promise<CaptchaToken>

接口入参: VerifyCaptchaDataRequest

字段	类型	必填	说明
token	string	是	验证码 token，从 adapter 的 captchaOptions.openURIWithCallback 回调 URL 参数中获取
key	string	是	用户输入的图形验证码答案

接口出参: CaptchaToken

字段	类型	说明
captcha_token	string	验证通过后返回的验证令牌
expires_in	number	令牌有效期（秒）

示例代码

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

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 在自定义适配器中使用
const adapter = {
  // 其他适配器配置...
  captchaOptions: {
    openURIWithCallback: async (url) => {
      // 解析 URL 参数
      const urlObj = new URL(url);
      const captchaData = urlObj.searchParams.get("captcha_data") || ""; // Base64 编码的验证码图片
      const state = urlObj.searchParams.get("state") || "";
      const token = urlObj.searchParams.get("token") || "";

      // 1. 展示验证码图片给用户（captchaData 为 Base64 编码的图片数据）
      // 2. 等待用户输入验证码
      const userInputKey = await showCaptchaDialogAndGetUserInput(captchaData);

      // 3. 调用 verifyCaptchaData 验证用户输入
      const captchaToken = await auth.verifyCaptchaData({
        token: token,
        key: userInputKey, // 用户输入的验证码
      });

      return captchaToken;
    },
  },
};

使用场景

当云开发检测到需要进行图形验证码验证时（如频繁登录等安全敏感操作），会触发适配器的 captchaOptions.openURIWithCallback 回调。开发者需要：

1. 从回调 URL 中解析 captcha_data（验证码图片）、token 等参数
2. 将验证码图片展示给用户
3. 获取用户输入的验证码答案
4. 调用 verifyCaptchaData 接口验证并获取 captchaToken
5. 将 captchaToken 作为 Promise 的返回值

Auth.verify()

提示

短信验证码 仅支持 上海 地域

接口描述

接口功能：验证码验证，包括短信验证码、邮箱验证码

接口声明：verify(params: VerifyRequest): Promise<VerifyResponse>

接口入参: VerifyRequest

字段	类型	必填	说明
verification_code	string	是	验证码，可通过Auth.getVerification获取
verification_id	string	是	验证码 ID，可通过Auth.getVerification获取

接口出参: VerifyResponse

字段	类型	必填	说明
verification_token	string	否	验证码 token

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 例：手机号验证码/ 邮箱验证码注册

// 第一步：用户点击获取验证码，调用如下方法发送短信验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const phoneNumber = "+86 13800000000";
const verificationInfo = await auth.getVerification({
  phone_number: phoneNumber,
});

/*
// 若使用邮箱验证，第一步代码改为
const email = "test@example.com"
const verificationInfo = await auth.getVerification({
  email: email
});
*/

// 第二步：等待用户在页面中输入验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证验证码
await auth.verify({
  verification_code: verificationCode,
  verification_id: verificationInfo.verification_id,
});

Auth.getVerification()

提示

获取短信验证码 仅支持 上海 地域

接口描述

接口功能：获取短信/邮件验证码

接口声明：getVerification(params: GetVerificationRequest): Promise<GetVerificationResponse>

接口入参: GetVerificationRequest

字段	类型	必填	说明
phone_number	string	否	手机号，中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”。与 email 二选一
email	string	否	邮箱，与 phone_number 二选一
target	Target	否	手机号或邮箱的应用场景

Target

值	含义
ANY	不校验手机号或邮箱是否存在，使用场景：注册或者登录这种，没有登录态的
USER	需要手机号或邮箱必须在系统中存在，且已经绑定用户

接口出参: GetVerificationResponse

字段	类型	说明
verification_id	string	验证码 id
is_user	boolean	是否是注册用户

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

const verificationCode = "000000";
const phoneNumber = "+86 13800000000";
// const email = "test@example.com";

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

Auth.sudo()

接口描述

接口功能：通过 sudo 接口获取高级操作权限，如修改密码（Auth.setPassword）、修改手机号（Auth.bindPhoneNumber）、修改邮箱（Auth.bindEmail）、删除用户（Auth.deleteMe）等操作

接口声明：Auth.sudo(params: SudoRequest): Promise<SudoResponse>

接口入参: SudoRequest

字段	类型	必填	说明
password	string	否	密码，password 和 verification_token 二选一，如果绑定了手机号，则必须使用 verification_token 进行 sudo
verification_token	string	否	token 令牌，通过账号绑定的手机号或邮箱验证获取，可通过Auth.verify获取

接口出参: SudoResponse

字段	类型	说明
sudo_token	string	高级权限 token 令牌, 如果用户只开启三方登录， 没有设置密码的情况下，sudo token 为 "" 空字符串

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 方式一：使用密码
const pass = "test_password";
const sudoRes = await auth.sudo({
  password: pass,
});
console.log(sudoRes.sudo_token);

// 方式二：通过邮箱验证码，手机号验证码获取。
// 当前账号绑定的邮箱地址或手机号
const email = "test@example.com";
// const phoneNumber = "+86 13800000000"

// 第一步：用户点击获取验证码，调用如下方法发送验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const verificationInfo = await auth.getVerification({
  email: email,
  //  phone_number: phoneNumber
});

// 第二步：等待用户在页面中输入验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证验证码
const verificationTokenRes = await auth.verify({
  verification_id: verificationInfo.verification_id,
  verification_code: verificationCode,
});

// 第四步：获取 sudo_token
const sudoRes = await auth.sudo({
  verification_token: verificationTokenRes.verification_token,
});
console.log(sudoRes.sudo_token);

// 可调用auth.setPassword、auth.bindEmail、auth.bindPhoneNumber、auth.deleteMe等方法

Auth.getAccessToken()

接口描述

接口功能：获取访问凭证 accessToken

接口声明：Auth.getAccessToken(): Promise<GetAccessTokenResponse>

接口入参: 无

接口出参: GetAccessTokenResponse

字段	类型	说明
accessToken	string	访问令牌
env	string	环境 id

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 某种方式登录后...

// 获取access_token
const { accessToken } = await auth.getAccessToken();

console.log(accessToken);

用户信息相关

Auth.getCurrentUser()

接口描述

接口功能：Auth.currentUser的异步操作，返回表示当前用户的 User 实例

接口声明：getCurrentUser(): Promise<User | null>

接口入参: 无

接口出参: User

详见 User

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});
const auth = app.auth();

// 执行某种登录之后...
const user = await auth.getCurrentUser();

Auth.bindPhoneNumber()

提示

仅支持 上海 地域

接口描述

接口功能：绑定手机号

接口声明：bindPhoneNumber(params: BindPhoneRequest): Promise<void>

接口入参: BindPhoneRequest

字段	类型	必填	说明
phone_number	string	是	新手机号，中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”
sudo_token	string	是	高级权限 token 令牌，可通过Auth.sudo获取
verification_token	string	是	验证码 token 令牌，可通过Auth.verify获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

// 前置条件，先登录
const auth = app.auth();

// 第一步：获取 sudo token， 参考 Auth.sudo 接口获取
const sudo_token = "test_sudo_token";

const phone_number = "+86 13800000000";

// 第二步：用户点击获取验证码，调用如下方法发送短信验证码，将 verificationInfo 存储到全局，方便第四步作为参数输入
const verificationInfo = await auth.getVerification({
  phone_number: phone_number,
});

// 第三步：等待用户在页面中输入短信验证码
const verificationCode = userInputCode; // 6位验证码

// 第四步：待用户输入完验证码之后，验证短信验证码
const verification_token_res = await auth.verify({
  verification_id: verificationInfo.verification_id,
  verification_code: verification_code,
});
const verification_token = verification_token_res.verification_token;

// 第五步：绑定手机号
await auth.bindPhoneNumber({
  phone_number: phone_number,
  sudo_token: sudo_token,
  verification_token: verification_token,
});

Auth.bindEmail()

接口描述

接口功能：更新邮箱地址

接口声明：bindEmail(params: BindEmailRequest): Promise<void>

接口入参: BindEmailRequest

字段	类型	必填	说明
email	string	是	邮箱地址
sudo_token	string	是	高级权限 token 令牌，可通过Auth.sudo获取
verification_token	string	是	验证码 token 令牌，可通过Auth.verify获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

// 前置条件，先登录
const auth = app.auth();


// 第一步：获取 sudo token， 参考 Auth.sudo 接口获取
const sudoToken = "test_sudo_token"

const newEmail = "new@example.com";

// 第二步：用户点击获取验证码，调用如下方法发送邮箱验证码，将 verificationInfo 存储到全局，方便第四步作为参数输入
const verificationInfo = await auth.getVerification({
  email: newEmail
});

// 第三步：等待用户在页面中输入短信验证码
const verificationCode = userInputCode; // 6位验证码

// 第四步：待用户输入完验证码之后，验证短信验证码
const newEmailTokenRes = await auth.verify({
  verification_id: verificationInfo.verification_id,
  verification_code: verificationCode,
});
const verificationToken = newEmailTokenRes.verification_token

// 第五步：绑定新邮箱
await auth.bindEmail({
  email: newEmail,
  sudo_token: sudoToken
  verification_token: verificationToken
});

Auth.setPassword()

接口描述

接口功能：设置密码（已登录状态下，更新用户密码）

接口声明 setPassword(params: SetPasswordRequest): Promise<void>

接口入参: SetPasswordRequest

字段	类型	必填	说明
new_password	string	是	新密码
sudo_token	string	是	高级权限 token 令牌，可通过Auth.sudo获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 第一步：获取 sudo token，参考 Auth.sudo 接口获取
const sudoToken = "test_sudo_token";

// 第二步：更新密码
const newPassWord = "test_new_password";
await auth.setPassword({
  new_password: newPassWord,
  sudo_token: sudoToken,
});

Auth.getUserInfo()

接口描述

接口功能：获取用户信息

接口声明：getUserInfo(): Promise<UserInfo>

接口入参: 无

接口出参: UserInfo

字段	类型	说明
name	string	用户昵称（区分与 登录用户名 username）
picture	string	用户上传头像
phone_number	string	用户绑定手机号
email_verified	boolean	用户是否经过邮箱验证
birthdate	string	用户生日
locale	string	用户设置语言
zoneinfo	string	时区
UserProfileProvider	UserProfileProvider	第三方平台配置

UserProfileProvider

字段	类型	必填	说明
id	string	否	默认内置的三方 provider_id，例如wx_open, wx_mp
provider_user_id	string	否	第三方 provider 用户 id (如 wxopenid)
name	string	否	名称

系统内置三方列表

provider_id	含义
wx_open	微信开放平台
wx_mp	微信公众号
google	google 平台

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
const userInfo = await auth.getUserInfo();

Auth.queryUser()

注意

自定义登录场景和匿名登录场景，不支持使用该接口查询用户信息（自定义登录场景请在业务服务中自行查询用户信息，匿名登录场景不支持）

接口描述

接口功能：查询用户，可通过用户名、邮箱、手机号任意参数查询

接口声明：queryUser(queryObj: QueryUserProfileRequest): Promise<QueryUserProfileResponse>;

接口入参: QueryUserProfileRequest

字段	类型	必填	说明
id	Array<string>	否	用户 uid 数组，最多支持查询 50 个 id 对应的用户
username	string	否	用户名称
email	string	否	邮箱
phone_number	string	否	手机号，中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”

接口出参: QueryUserProfileResponse

字段	类型	必填	说明
total	string	否	数量
data	SimpleUserProfile[]	否	用户列表

SimpleUserProfile

字段	类型	必填	说明
sub	string	是	下标
name	string	是	名称
picture	string	否	图片
gender	string	否	性别
locale	string	否	地点
email	string	否	邮箱
phone_number	string	否	手机号

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
// const email = "test@example.com";
// const phoneNumber = "+86 13800000000";
const username = "test_username";

const userInfo = await auth.queryUser({
  username: username,
  // email,
  // phone_number: phoneNumber,
});

Auth.resetPassword()

提示

手机号验证码方式 仅支持 上海 地域

接口描述

接口功能：重置密码（用户忘记密码无法登录时，可使用该接口强制设置密码）

接口声明：resetPassword(params: ResetPasswordRequest): Promise<void>

接口入参: ResetPasswordRequest

字段	类型	必填	说明
email	string	否	邮箱， 与 phone_number 二选一
phone_number	string	否	手机号，与 email 二选一，中国手机号要带上“+86 ”国家码，例如“+86 138xxxxxxxxx”
new_password	string	是	新密码
verification_token	string	是	验证码 token 令牌，可通过Auth.verify获取

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();
const email = "testexample.com";
const newPassword = "test_new_password";
const phoneNumber = "+86 13800000000";

// 第一步：用户点击获取验证码，调用如下方法发送短信验证码，将 verificationInfo 存储到全局，方便第三步作为参数输入
const verificationInfo = await auth.getVerification({
  phone_number: phoneNumber,
});

// 第二步：等待用户在页面中输入短信验证码
const verificationCode = userInputCode; // 6位验证码

// 第三步：待用户输入完验证码之后，验证短信验证码
const verificationToken = await auth.verify({
  verification_id: verificationInfo.verification_id,
  verification_code: verificationCode,
});

await auth.resetPassword({
  // email: email,
  phone_number: phoneNumber,
  new_password: newPassword,
  verification_token: verificationToken.verificationToken,
});

Auth.isUsernameRegistered()

接口描述

接口功能：检查用户名是否存在。

接口声明：isUsernameRegistered(username: string): Promise<boolean>

接口入参

字段	类型	必填	说明
username	string	是	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文

接口出参: boolean

值	含义
true	存在
false	不存在

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

const username = "your_awesome_username";
const exist = await auth.isUsernameRegistered(username);

Auth.deleteMe()

接口描述

接口功能：删除用户。

接口声明：deleteMe(params: WithSudoRequest): Promise<UserProfile>

接口入参: WithSudoRequest

字段	类型	必填	说明
sudo_token	string	是	高级权限 token 令牌，可通过Auth.sudo获取

接口出参: UserProfile

字段	类型	说明
sub	string	用户唯一标识）
name	string	用户昵称（区分与 登录用户名 username）
username	string	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文
picture	string	用户上传头像
phone_number	string	用户绑定手机号
email	string	用户绑定邮箱
email_verified	boolean	用户是否经过邮箱验证
groups	Array<{id: string; expires_at?: string}>	用户所属组/角色列表（字符串数组）
gender	string	性别
birthdate	string	用户生日
locale	string	用户设置语言
zoneinfo	string	时区
providers	Array<UserProfileProvider>	第三方平台配置

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

// 1. 通过 sudo 操作获取 sudo_token，参考 Auth.sudo 方法

// 2. deleteMe

const user = await auth.deleteMe({
  sudo_token: "your sudo_token",
});

Auth.loginScope()

接口描述

接口功能：查询用户的权限范围，可以用来判断是否为匿名登录状态

接口声明：loginScope(): Promise<string>

接口入参: 无

接口出参: string

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  region: "ap-shanghai", // 不传默认为上海地域
});

const auth = app.auth();

const username = "your_awesome_username";

// 经过某种方式登录后...

const loginScope = await auth.loginScope();
if (loginScope === "anonymous") {
  console.log("当前为匿名登录方式");
}

LoginState

LoginState 对象是对用户当前的登录态的抽象

Auth.hasLoginState()

接口描述

接口功能：返回当前登录状态 LoginState，如果未登录，则返回 null

接口声明：hasLoginState(): LoginState | null

接口入参: 无

接口出参: LoginState

详见 LoginState，返回 null 则表示当前未登录

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

const loginState = app.auth().hasLoginState();

if (loginState) {
  // 登录态有效
} else {
  // 没有登录态，或者登录态已经失效
}

Auth.getLoginState()

接口描述

接口功能：Auth.hasLoginState()的异步操作，返回当前登录状态 LoginState，返回 null 则表示当前未登录

接口声明：getLoginState(): Promise<LoginState | null>

提示

此 API 是 hasLoginState 的异步模式，适用于本地存储为异步的平台，比如 React Native

接口入参: 无

接口出参: LoginState

详见 LoginState，返回 null 则表示当前未登录

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

const loginState = await app.auth().getLoginState();

if (loginState) {
  // 登录态有效
} else {
  // 没有登录态，或者登录态已经失效
}

Auth.onLoginStateChanged()

接口描述

接口功能：监听登录状态变化，当登录状态发生变化时会触发该函数。比如调用注册/登录/登出相关接口、或者 Credentials 出现异常(如'credentials not found'、'no refresh token found in credentials'错误)等。

接口声明：onLoginStateChanged(callback: Function): Promise<void>

接口入参: OnLoginStateChangedParams

字段	类型	必填	说明
callback	Function	是	回调函数

callback 回调函数入参定义

字段	类型	说明
name	string	默认值为 loginStateChanged
data	object	包括 { msg?: string; eventType: 'sign_in' | 'sign_out' | 'credentials_error' }

提示

如果 eventType 是 sign_in 或 sign_out，还会返回当前登录状态 LoginState

接口出参: 无

示例代码

const app = cloudbase.init({
  env: "xxxx-yyy",
  clientId: "xxxx",
  region: "ap-shanghai", // 不传默认为上海地域
});

app.auth().onLoginStateChanged((params) => {
  console.log(params);
  const { eventType } = params?.data || {};
  switch (eventType) {
    case "sign_in":
      // 登录成功
      break;
    case "sign_out":
      // 退出登录成功
      break;
    case "credentials_error":
      // 权限失效
      break;
    default:
      return;
  }
});

LoginState.user

类型：User | null

表示当前用户，具体请参考 User

如果没有登录，则为 null

User

User.update()

接口描述

接口功能：更新用户信息

接口声明：update(userInfo): Promise<void>

接口入参: userInfo

字段	类型	必填	说明
name	string	否	用户昵称（区分与 登录用户名 username）
username	string	否	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文
picture	string	否	用户上传头像
phone_number	string	否	用户绑定手机号
email	string	否	用户绑定邮箱
gender	string	否	性别，取值仅限于 MALE、FEMALE、UNKNOWN
birthdate	string	否	用户生日

接口出参: 无

示例代码

const user = auth.currentUser;

user
  .update({
    gender: "MALE", // 性别，取值仅限于 MALE、FEMALE、UNKNOWN
  })
  .then(() => {
    // 更新用户信息成功
  });

User.refresh()

接口描述

接口功能：刷新本地用户信息。当用户在其他客户端更新用户信息之后，可以调用此接口同步更新之后的信息。

接口声明：refresh(): Promise<UserInfo>

接口入参: 无

接口出参: UserInfo

字段	类型	说明
sub	string	用户唯一标识）
name	string	用户昵称（区分与 登录用户名 username）
username	string	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文
picture	string	用户上传头像
phone_number	string	用户绑定手机号
email	string	用户绑定邮箱
email_verified	boolean	用户是否经过邮箱验证
groups	Array<{id: string; expires_at?: string}>	用户所属组/角色列表（字符串数组）
gender	string	性别
birthdate	string	用户生日
locale	string	用户设置语言
zoneinfo	string	时区
providers	Array<UserProfileProvider>	第三方平台配置

示例代码

const user = auth.currentUser;

user.refresh().then((userInfo) => {
  // 刷新用户信息成功
});

错误码

登录错误

错误码	说明
not_found	用户不存在
password_not_set	当前用户未设置密码，请使用验证码登录或第三方登录方式
invalid_password	密码不正确
user_pending	该用户未激活
user_blocked	该用户被停用
invalid_status	您已经超过了密码最大重试次数， 请稍后重试
invalid_two_factor	二次验证码不匹配或已过时

注册错误

错误码	说明
failed_precondition	你输入的手机号或邮箱已被注册，请使用其他号码

验证码相关错误

错误码	说明
failed_precondition	从第三方获取用户信息失败
resource_exhausted	你尝试过于频繁，请稍后重试
invalid_argument	您输入的验证码不正确或已过期
aborted	你尝试的次数过多，请返回首页，稍后重试
permission_denied	您当前的会话已过期，请返回重试
captcha_required	需要输入验证码, 需根据反机器人服务接入
captcha_invalid	验证码不正确, 需根据反机器人服务接入

其他错误

错误码	说明
unreachable	网络错误，请检查您的网络连接，稍后重试

错误描述

错误码	错误描述	说明
permission_denied	cors permission denied,please check if {url} in your client {env} domains	请在”云开发平台-环境配置-安全来源-安全域名”中检查对应{env}环境下是否已经配置了安全域名{url}，配置后 10 分钟生效

验证码相关处理

error==captcha_required 或 error==captcha_invalid 表示请求触发了验证码相关逻辑。需要进行机器验证。

验证码流程完成后，若业务接口返回 error 等于 captcha_required，表示请求需要 captcha_token 参数，尽可能使用本地的未过期的验证码。当 error 等于 captcha_invalid 时，表示验证码无效，需要需要重新获取验证码。在同一个验证流程内，captcha_invalid 最多尝试一次即可。

如需使用 adapter 进行处理，请参考adapter 的验证码处理指南

初始化验证码

curl -X POST "https://${env}.ap-shanghai.tcb-api.tencentcloudapi.com/auth/v1/captcha/init" \
   -H "Content-Type:application/json" \
   -u ${clientID}:${clientSecrect}
   -d \
'{
  "redirect_uri": "https://example.com/callback",
  "state": "your_state string"
}'

请求参数

redirect_uri: (必传) 验证码验证完成后的地址。 state: (必传) 系统状态字符串，该字符串在验证码验证完成后后将 state 携带到。

响应 1：状态码 200 且返回 url 字段非空，需要展示验证码并完成验证

如果用户请求比较频繁或存在其他风险，验证码服务会返回下面的形式。

{
  "url": "https://exmaple.com/captcha.html",
  "expires_in": 600
}

此时表示，用户行为需要经过验证码验证才可以通过，请求成功后，客户端通过浏览器或 webview/iframe 等 打开 url 地址，比如上面的https://exmaple.com/captcha.html 用户在 web 中处理完成后，会自动重定向到下面的地址：（其中 captcha_token 为验证码 token，expires_in 为过期时间，单位为秒）， https://example.com/callback?state=xxxxx&captcha_token=hbGciOiJeyJhbGciOiJSUAeyJhbGciOiJ&expires_in=600

业务方需要监听 redirect_uri 的地址变化，当地址为 appanme://com.package.name/callback 时，比对 state 是否和传入的相同，并获取到 captcha_token 和 expires_in。

若验证过程发生错误，验证页面会展示错误信息，用户点击返回后，验证页面会将错误信息 error 和 error_description 拼接到 redirect_uri 后重定向，例如：

https://example.com/callback?state=xxxxx&error=xxx&error_description=xxx

此时业务方可以根据需要恢复初始页或做其它处理。

响应 2：状态码非 200，需要进行错误处理

如果用户请求比较频繁或存在其他风险，验证码服务会返回下面的形式。

{
  "error": "resource_exhausted",
  "error_description": "Your operation is too frequent, please try again later"
}

此时客户端需要展示 error_descriprion, 可以结合 i18n 展示进行多语言展示。

拿到 captcha_token 再次请求

拿到 captcha_token 后，将 captcha_token 放到 url 参数中进行请求；

比如，请求 /v1/example 返回 captcha_invalid 错误，此时，则需要再次请求 /v1/example?captcha_token=hbGciOiJeyJhbGciOiJSUAeyJhbGciOiJ 即可完成操作。

类型定义

User

User 对象是当前用户信息的抽象

属性	类型	说明
uid	string | undefined	用户唯一标识
gender	string | undefined	性别
picture	string | undefined	头像 URL
email	string | undefined	​ 邮箱
emailVerified	boolean | undefined	​ 邮箱是否已验证
phoneNumber	string | undefined	手机号
username	string | undefined	用户名称，长度 5-24 位，支持字符中英文、数字、特殊字符（仅支持_-），不支持中文
name	string | undefined	用户昵称
providers	Array<{ id?: string; providerUserId?: string; name?: string }> | undefined	第三方登录绑定列表
birthdate	string | undefined	出生日期
sub	string | undefined	身份主体标识（JWT sub）

Credentials

Credentials 对象定义了用于身份认证与授权的凭据信息结构

属性	类型	说明
token_type	string | null	令牌类型，常见值为 Bearer​ 等，用于指示令牌的认证方案
access_token	string | null	访问令牌，用于调用受保护资源的身份凭证
refresh_token	string | null	刷新令牌，用于在访问令牌过期后获取新的访问令牌
scope	string | null	权限范围，通常为空格分隔的字符串（如 "openid profile email"）
expires_in	number | null	访问令牌的有效期，单位为秒
expires_at	Date | null	访问令牌的过期时间点
sub	string | null	用户唯一标识
groups	string[] | null	用户所属组/角色列表（字符串数组）
version	string	凭据的版本号或来源标识

LoginState

LoginState 对象是对用户当前的登录态的抽象

属性	类型	说明
user	User	User 对象
oauthLoginState	Credentials | null	Credentials 对象