跳到主要内容

身份认证

signUp​

Future<SignUpRes> auth.signUp(SignUpReq params)

注册新用户账户，采用智能注册并登录流程。

  • 创建一个新的用户账户
  • 采用智能注册并登录流程：发送验证码 → 等待用户输入 → 智能判断用户存在性 → 自动登录或注册并登录
  • 如果用户已存在则直接登录，如果用户不存在则注册新用户并自动登录

参数

params
SignUpReq

返回

Future
SignUpRes

示例

final result = await auth.signUp(SignUpReq(
  email: 'user@example.com',
  password: 'securePassword123',
  nickname: '新用户',
));

if (result.error != null) {
  print('注册失败: ${result.error!.message}');
  return;
}

// 验证码验证
final verifyResult = await result.data!.verifyOtp!(
  VerifyOtpParams(token: '123456'),
);

if (verifyResult.isSuccess) {
  print('注册成功: ${verifyResult.data?.user?.id}');
}

signInAnonymously​

Future<SignInRes> auth.signInAnonymously({String? providerToken})

匿名登录，创建一个临时匿名用户账户。

  • 创建一个临时匿名用户账户
  • 无需提供任何身份验证信息
  • 适合需要临时访问权限的场景

参数

providerToken
String?

第三方平台令牌，用于关联第三方平台身份

返回

Future
SignInRes

示例

final result = await auth.signInAnonymously();

if (result.isSuccess) {
  print('匿名登录成功');
  print('用户ID: ${result.data?.user?.id}');
  print('是否匿名: ${result.data?.user?.isAnonymous}');
} else {
  print('匿名登录失败: ${result.error!.message}');
}

signInWithPassword​

Future<SignInRes> auth.signInWithPassword(SignInWithPasswordReq params)

使用密码登录。支持通过用户名、邮箱或手机号进行登录。

参数

params
SignInWithPasswordReq

返回

Future
SignInRes

示例

final result = await auth.signInWithPassword(
  SignInWithPasswordReq(
    email: 'user@example.com',
    password: 'securePassword123',
  ),
);

if (result.isSuccess) {
  print('登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithUsername​

Future<SignInRes> auth.signInWithUsername({
  required VerificationInfo verificationInfo,
  required String verificationCode,
  required String username,
  String? loginType,
  dynamic bindInfo,
})

使用用户名/邮箱/手机号和验证码登录。通常先调用 getVerification 发送验证码，再将返回的验证信息与用户输入的验证码传入本方法完成登录。

  • 若 verificationInfo.isUser 为 true，则走登录流程
  • 若用户不存在，则自动注册并登录
  • 可通过 bindInfo 在登录或注册时绑定第三方身份源

参数

verificationInfo
VerificationInfo

验证信息，通常来自 getVerification 的返回值

verificationCode
String

用户输入的验证码

username
String

用户名、邮箱或手机号

loginType
String?

登录类型：email 或 phone。为 email 时按邮箱处理，否则按手机号处理（自动补全 +86 前缀）

bindInfo
dynamic

绑定第三方身份源信息，如 {'providerToken': '...'} 或 {'providerId': '...'}

返回

Future
SignInRes

示例

final verification = await auth.getVerification(email: 'user@example.com');

if (verification.error != null) {
  print('发送验证码失败: ${verification.error!.message}');
  return;
}

final result = await auth.signInWithUsername(
  verificationInfo: VerificationInfo(
    verificationId: verification.data!.verificationId,
    isUser: verification.data!.isUser,
  ),
  verificationCode: '123456',
  username: 'user@example.com',
  loginType: 'email',
);

if (result.isSuccess) {
  print('登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithOtp​

Future<SignInWithOtpRes> auth.signInWithOtp(SignInWithOtpReq params)

使用 OTP（一次性验证码）登录。调用后发送验证码，需通过返回的 verifyOtp 回调完成验证。

  • 如果用户不存在，会默认注册用户，可以通过 shouldCreateUser参数控制是否自动创建用户，默认为 true

参数

params
SignInWithOtpReq

返回

Future
SignInWithOtpRes

示例

final result = await auth.signInWithOtp(
  SignInWithOtpReq(email: 'user@example.com'),
);

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

// 用户输入验证码后调用
final loginResult = await result.data!.verifyOtp!(
  VerifyOtpParams(token: '123456'),
);

if (loginResult.isSuccess) {
  print('OTP 登录成功: ${loginResult.data?.user?.id}');
}

signInWithOAuth​

Future<SignInOAuthRes> auth.signInWithOAuth(SignInWithOAuthReq params)

使用 OAuth 第三方平台登录。返回授权 URL，需引导用户跳转至该 URL 完成授权。

参数

params
SignInWithOAuthReq

返回

Future
SignInOAuthRes

示例

final result = await auth.signInWithOAuth(
  SignInWithOAuthReq(provider: 'wechat'),
);

if (result.isSuccess) {
  final authUrl = result.data!.url!;
  print('请跳转到授权页面: $authUrl');
  // 引导用户打开 authUrl 进行授权
}

signInWithIdToken​

Future<SignInRes> auth.signInWithIdToken(SignInWithIdTokenReq params)

使用第三方平台的身份令牌（IdToken）登录，适用于已获取微信、Google 等平台令牌的场景。SDK 会将 provider 作为 provider_id、将 token 作为 provider_id_token 发送给登录接口。

参数

params
SignInWithIdTokenReq

返回

Future
SignInRes

示例

final result = await auth.signInWithIdToken(
  SignInWithIdTokenReq(
    token: 'provider-id-token',
    provider: 'wechat',
  ),
);

if (result.isSuccess) {
  print('IdToken 登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithCustomTicket​

Future<SignInRes> auth.signInWithCustomTicket(Future<String> Function() getTicketFn)

使用自定义票据登录。通过传入获取票据的异步函数，由服务端生成票据并完成登录。

参数

getTicketFn
Future<String> Function()

获取自定义登录票据的异步函数

返回

Future
SignInRes

示例

final result = await auth.signInWithCustomTicket(() async {
  // 从您的服务端获取自定义票据
  final ticket = await fetchTicketFromServer();
  return ticket;
});

if (result.isSuccess) {
  print('自定义票据登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

会话管理​

getSession​

Future<SignInRes> auth.getSession();

获取当前会话。如果 Token 已过期会自动刷新。

参数

无参数

返回

Future
SignInRes

示例

final result = await auth.getSession();

if (result.isSuccess) {
  final session = result.data?.session;
  print('Access Token: ${session?.accessToken}');
  print('用户: ${result.data?.user?.id}');
} else {
  print('获取会话失败: ${result.error!.message}');
}

refreshSession​

Future<SignInRes> auth.refreshSession([String? refreshToken])

刷新会话。使用 Refresh Token 获取新的 Access Token。

参数

refreshToken
String?

刷新令牌（可选，默认使用当前会话的 refreshToken）

返回

Future
SignInRes

示例

final result = await auth.refreshSession();

if (result.isSuccess) {
  print('会话已刷新');
  print('新 Access Token: ${result.data?.session?.accessToken}');
} else {
  print('刷新失败: ${result.error!.message}');
}

setSession​

Future<SignInRes> auth.setSession(SetSessionReq params)

设置会话。通过 Refresh Token 恢复会话状态。

参数

params
SetSessionReq

返回

Future
SignInRes

示例

final result = await auth.setSession(
  SetSessionReq(refreshToken: 'your-refresh-token'),
);

if (result.isSuccess) {
  print('会话设置成功: ${result.data?.user?.id}');
}

signOut​

Future<SignOutRes> auth.signOut([SignOutReq? params])

退出登录。用当前 access token 调用吊销接口，并清除本地会话。params 不会发给服务端。

参数

params
SignOutReq?

登出配置选项（可选）

返回

Future
SignOutRes

示例

await auth.signOut();
print("已退出登录");

onAuthStateChange​

OnAuthStateChangeResult auth.onAuthStateChange(OnAuthStateChangeCallback callback)

监听认证状态变化。支持监听登录、登出、Token 刷新和用户更新等事件。

参数

callback
void Function(AuthStateChangeEvent, Session?, AuthStateChangeInfo?)

状态变化回调函数

返回

OnAuthStateChangeResult
OnAuthStateChangeResult

示例

final result = auth.onAuthStateChange((event, session, info) {
  print('认证状态变化: ${event.value}');
  if (session != null) {
    print('用户: ${session.user?.id}');
  }
});

// 取消监听
result.data?.subscription.unsubscribe();

getClaims​

Future<GetClaimsRes> auth.getClaims();

获取当前 Access Token 的 JWT Claims（令牌声明）。

参数

无参数

返回

Future
GetClaimsRes

示例

final result = await auth.getClaims();

if (result.isSuccess) {
  final claims = result.data?.claims;
  print('用户ID: ${claims?.sub}');
  print('邮箱: ${claims?.email}');
  print('用户组: ${claims?.groups}');
  print('过期时间: ${claims?.exp}');
}

用户管理​

getUser​

Future<GetUserRes> auth.getUser();

获取当前登录用户信息。

参数

无参数

返回

Future
GetUserRes

示例

final result = await auth.getUser();

if (result.isSuccess) {
  final user = result.data?.user;
  print('用户ID: ${user?.id}');
  print('邮箱: ${user?.id}');
  print('昵称: ${user?.userMetadata?.nickName}');
} else {
  print('获取用户信息失败: ${result.error!.message}');
}

refreshUser​

Future<SignInRes> auth.refreshUser();

刷新用户信息。重新从服务端获取最新的用户数据并更新本地会话。

参数

无参数

返回

Future
SignInRes

示例

final result = await auth.refreshUser();

if (result.isSuccess) {
  print('用户信息已刷新: ${result.data?.user?.id}');
}

updateUser​

Future<UpdateUserRes> auth.updateUser(UpdateUserReq params)

更新用户信息。如果更新邮箱或手机号，需要通过验证码验证。

参数

params
UpdateUserReq

返回

Future
UpdateUserRes

示例

final result = await auth.updateUser(
  UpdateUserReq(nickname: '新昵称', avatarUrl: 'https://example.com/avatar.png'),
);

if (result.isSuccess) {
  print('用户信息已更新: ${result.data?.user?.userMetadata?.nickName}');
}

deleteUser​

Future<CloudBaseResponse<void>> auth.deleteUser(DeleteUserReq params)

删除当前用户。需要提供密码进行安全验证。

参数

params
DeleteUserReq

返回

Future
CloudBaseResponse<void>

示例

final result = await auth.deleteUser(
  DeleteUserReq(password: 'currentPassword'),
);

if (result.isSuccess) {
  print('用户已删除');
} else {
  print('删除失败: ${result.error!.message}');
}

身份源管理​

getUserIdentities​

Future<GetUserIdentitiesRes> auth.getUserIdentities();

获取当前用户已绑定的身份源列表。

参数

无参数

返回

Future
GetUserIdentitiesRes

示例

final result = await auth.getUserIdentities();

if (result.isSuccess) {
  for (final identity in result.data?.identities ?? []) {
    print('身份源: ${identity.name} (${identity.provider})');
  }
}

linkIdentity​

Future<LinkIdentityRes> auth.linkIdentity(LinkIdentityReq params)

绑定第三方身份源。会跳转到第三方授权页面完成绑定。

参数

params
LinkIdentityReq

返回

Future
LinkIdentityRes

示例

final result = await auth.linkIdentity(
  LinkIdentityReq(provider: 'wechat'),
);

if (result.isSuccess) {
  print('授权地址: ${result.data?.url}');
}

unlinkIdentity​

Future<CloudBaseResponse<void>> auth.unlinkIdentity(UnlinkIdentityReq params)

解绑第三方身份源。

参数

params
UnlinkIdentityReq

返回

Future
CloudBaseResponse<void>

示例

final result = await auth.unlinkIdentity(
  UnlinkIdentityReq(provider: 'wechat'),
);

if (result.isSuccess) {
  print('身份源已解绑');
}

密码管理​

resetPasswordForEmail​

Future<ResetPasswordForEmailRes> auth.resetPasswordForEmail(String emailOrPhone, {String? redirectTo})

通过邮箱或手机号重置密码。调用后发送验证码，需通过返回的 updateUser 回调完成密码重置。

参数

emailOrPhone
String

邮箱或手机号

redirectTo
String?

重定向地址

返回

Future
ResetPasswordForEmailRes

示例

final result = await auth.resetPasswordForEmail('user@example.com');

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

// 用户收到验证码后
final resetResult = await result.data!.updateUser!(
  UpdateUserAttributes(nonce: '123456', password: 'newPassword123'),
);

if (resetResult.isSuccess) {
  print('密码重置成功，已自动登录');
}

resetPasswordForOld​

Future<SignInRes> auth.resetPasswordForOld(ResetPasswordForOldReq params)

通过旧密码重置密码。

参数

params
ResetPasswordForOldReq

返回

Future
SignInRes

示例

final result = await auth.resetPasswordForOld(
  ResetPasswordForOldReq(
    oldPassword: 'oldPassword123',
    newPassword: 'newPassword456',
  ),
);

if (result.isSuccess) {
  print('密码修改成功');
} else {
  print('密码修改失败: ${result.error!.message}');
}

reauthenticate​

Future<ReauthenticateRes> auth.reauthenticate();

重新认证。发送验证码到用户邮箱或手机号，验证后可进行敏感操作（如设置新密码）。

参数

无参数

返回

Future
ReauthenticateRes

示例

final result = await auth.reauthenticate();

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

final authResult = await result.data!.updateUser!(
  UpdateUserAttributes(nonce: '123456', password: 'newSecurePassword'),
);

if (authResult.isSuccess) {
  print('重新认证成功');
}

验证管理​

getVerification​

Future<CloudBaseResponse<GetVerificationResData>> auth.getVerification({String? email, String? phoneNumber})

发送验证码到邮箱或手机号。

参数

email
String?

邮箱（与 phoneNumber 二选一）

phoneNumber
String?

手机号（与 email 二选一）

返回

Future
CloudBaseResponse<GetVerificationResData>

示例

final result = await auth.getVerification(email: 'user@example.com');

if (result.isSuccess) {
  print('验证码已发送，验证ID: ${result.data?.verificationId}');
  print('是否已注册用户: ${result.data?.isUser}');
}

verify​

Future<CloudBaseResponse<VerifyCodeResData>> auth.verify({required String verificationId, required String verificationCode})

验证验证码。

参数

verificationId
String

验证 ID

verificationCode
String

验证码

返回

Future
CloudBaseResponse<VerifyCodeResData>

示例

final result = await auth.verify(
  verificationId: 'verification-id',
  verificationCode: '123456',
);

if (result.isSuccess) {
  print('验证成功，令牌: ${result.data?.verificationToken}');
}

verifyOAuth​

Future<VerifyOAuthRes> auth.verifyOAuth([VerifyOAuthReq? params])

验证 OAuth 回调，完成第三方登录或绑定身份。如果未传入参数，会自动从当前页面 URL 中提取 code 和 state。

参数

params
VerifyOAuthReq?

OAuth 回调参数（可选，不传时自动从 URL 中获取）

返回

Future
VerifyOAuthRes

示例

// 自动从 URL 获取 code 和 state
final result = await auth.verifyOAuth();

if (result.isSuccess) {
  print('OAuth 验证成功: ${result.data?.user?.id}');
}

// 手动传入参数
final result2 = await auth.verifyOAuth(VerifyOAuthReq(
  code: 'authorization-code',
  state: 'state-value',
  provider: 'google',
  redirectUri: 'https://example.com/callback',
));

verifyOtp​

Future<SignInRes> auth.verifyOtp(VerifyOtpReq params)

验证 OTP 并登录。

参数

params
VerifyOtpReq

返回

Future
SignInRes

示例

final result = await auth.verifyOtp(VerifyOtpReq(
  email: 'user@example.com',
  token: '123456',
  messageId: 'message-id',
));

if (result.isSuccess) {
  print('验证并登录成功: ${result.data?.user?.id}');
}

resend​

Future<ResendRes> auth.resend(ResendReq params)

重发验证码。

参数

params
ResendReq

返回

Future
ResendRes

示例

final result = await auth.resend(
  ResendReq(email: 'user@example.com', type: ResendType.signup),
);

if (result.isSuccess) {
  print('验证码已重发，消息ID: ${result.data?.messageId}');
}

getCaptchaToken​

Future<String?> app.captcha.getCaptchaToken({bool forceNew = false, required String state})

获取有效的验证码 Token，在多次出现密码输入错误或频繁发送验证码时会要求提供验证码 Token。优先从缓存获取，若无缓存则自动创建验证码并弹出验证界面。支持自定义验证码处理器或使用内置弹窗。

参数

forceNew
bool

是否强制创建新验证码（默认 false）

state
String

状态标识

返回

Future
String?

验证码 Token，失败时为 null

示例

// 初始化时配置 navigatorKey
final navigatorKey = GlobalKey<NavigatorState>();

final app = await CloudBase.init(
  env: 'your-env-id',
  captchaConfig: CaptchaConfig(navigatorKey: navigatorKey),
);

// 获取验证码 Token（自动弹出验证码弹窗）
final token = await app.captcha.getCaptchaToken(state: 'login');
print('Captcha Token: $token');

appendCaptchaTokenToUrl​

Future<String> app.captcha.appendCaptchaTokenToUrl(
  String url, {
  required String state,
  bool forceNew = false,
})

取得验证码 Token，并把它接到 URL 上。没有拿到 Token 时返回原 URL。

参数

url
String

原始 URL

state
String

状态标识

forceNew
bool

是否强制创建新验证码，默认 false

返回

Future
String

带 captcha_token 的 URL；未取得 Token 时为原 URL

示例

final url = await app.captcha.appendCaptchaTokenToUrl(
  'https://example.com/callback',
  state: 'login',
);

createCaptchaData​

Future<CreateCaptchaDataRes> app.captcha.createCaptchaData({required String state})

创建验证码数据。返回验证码图片数据和 Token。

参数

state
String

状态标识

返回

Future
CreateCaptchaDataRes

示例

final captchaData = await app.captcha.createCaptchaData(state: 'login');
print('验证码图片: ${captchaData.data}');
print('Token: ${captchaData.token}');

verifyCaptchaData​

Future<VerifyCaptchaRes> app.captcha.verifyCaptchaData({required String token, required String key})

验证用户输入的验证码。

参数

token
String

验证码 Token

key
String

用户输入的验证码

返回

Future
VerifyCaptchaRes

示例

final result = await app.captcha.verifyCaptchaData(
  token: captchaData.token,
  key: '用户输入的验证码',
);
print('验证码 Token: ${result.captchaToken}');

clearCaptchaToken​

Future<void> app.captcha.clearCaptchaToken()

清除本地缓存的验证码 Token。

参数

无参数

返回

Future
void

无返回值

示例

await app.captcha.clearCaptchaToken();
print("验证码 Token 已清除");