Auth API

Auth API 提供 6 个方法，用于通过邮箱 OTP 或钱包签名对用户进行身份验证、刷新会话、获取当前用户以及退出登录。

方法

方法	参数	返回值	说明
sendEmailOtp(email)	email: string	ApiResponse<{ sent: boolean }>	向指定邮箱地址发送一次性密码。
verifyEmailOtp(email, otp)	email: string, otp: string	ApiResponse<EngineAuthResponse>	验证 OTP 并返回 token 和用户资料。
authWithWallet(walletAddress, signature, message)	walletAddress: string, signature: string, message: string	ApiResponse<EngineAuthResponse>	通过用户钱包的签名消息进行身份验证。
refreshToken(refreshToken)	refreshToken: string	ApiResponse<EngineAuthResponse>	使用 refresh token 换取新的 access/refresh token 对。
getCurrentUser()	--	ApiResponse<User>	返回当前已验证用户的资料。
signOut()	--	ApiResponse<{ success: boolean }>	在服务端使当前会话失效。

类型

EngineAuthResponse

interface EngineAuthResponse {
  /** JWT access token. Pass to engine.setAccessToken(). */
  accessToken: string;
  /** Refresh token for obtaining new access tokens. */
  refreshToken: string;
  /** Access token expiry in seconds from now. */
  expiresIn: number;
  /** Authenticated user profile. */
  user: User;
}

User

interface User {
  id: string;
  email?: string;
  walletAddress?: string;
  displayName?: string;
  avatarUrl?: string;
  role: 'user' | 'admin';
  createdAt: string;
  updatedAt: string;
}

邮箱 OTP 流程

第 1 步 -- 发送 OTP

const res = await engine.sendEmailOtp('user@example.com');

if (res.success) {
  console.log('OTP sent');
} else {
  console.error('Failed to send OTP:', res.error);
}

第 2 步 -- 验证 OTP

const authRes = await engine.verifyEmailOtp('user@example.com', '482901');

if (authRes.success && authRes.data) {
  // Store tokens
  engine.setAccessToken(authRes.data.accessToken);
  // Persist refresh token for later
  await secureStore.set('refreshToken', authRes.data.refreshToken);
  console.log('Welcome', authRes.data.user.displayName);
}

钱包签名流程

// 1. Generate a sign-in message (app-defined)
const message = `Sign in to ONE\nNonce: ${crypto.randomUUID()}`;

// 2. Have the user sign the message with their wallet
const signature = await walletClient.signMessage({ message });

// 3. Send to the engine for verification
const authRes = await engine.authWithWallet(
  walletClient.account.address,
  signature,
  message
);

if (authRes.success && authRes.data) {
  engine.setAccessToken(authRes.data.accessToken);
}

Token 刷新

Access token 在 expiresIn 秒后过期。使用 refresh token 获取新的凭证，无需用户重新进行身份验证。

const stored = await secureStore.get('refreshToken');
const res = await engine.refreshToken(stored);

if (res.success && res.data) {
  engine.setAccessToken(res.data.accessToken);
  await secureStore.set('refreshToken', res.data.refreshToken);
}

获取当前用户

随时获取已验证用户的资料：

const userRes = await engine.getCurrentUser();

if (userRes.success && userRes.data) {
  console.log('User ID:', userRes.data.id);
  console.log('Email:', userRes.data.email);
  console.log('Role:', userRes.data.role);
}

退出登录

在服务端使当前会话失效：

const res = await engine.signOut();

if (res.success) {
  // Clear local state
  engine.setAccessToken('');
  await secureStore.delete('refreshToken');
}

错误场景

场景	error 字符串
OTP 无效或已过期	"invalid_otp"
邮箱未找到	"user_not_found"
钱包签名无效	"invalid_signature"
Refresh token 已过期	"token_expired"
未设置 access token	"unauthorized"

下一步

• Wallet API -- 查询余额并提交交易。
• Engine Client -- 了解 setAccessToken 的底层工作原理。