> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 通行密钥登录

通过浏览器交接完成免密码登录，并把会话带回应用。

## 交接流程如何运作

通行密钥登录在应用中发起、在系统浏览器中完成。应用通过 WebBrowser.openAuthSessionAsync 打开 {API URL}/auth?mobile_callback=<deep link>；网页完成任意登录方式后调用 GET /api/auth/mobile-handoff，随即重定向回 <scheme>://auth/callback，并携带会话 Cookie 和一个 state nonce。

每次尝试都会生成一个全新的 nonce，且必须原样往返 —— state 参数不匹配会被判为 stateMismatch，因此过期或伪造的回调无法注入会话。返回的 Cookie 会合入 Better Auth Expo 客户端使用的同一个 SecureStore 存储（supastack.auth_cookie），随后通知会话存储，已登录的应用界面随之渲染。

用户关掉浏览器弹层时会得到静默的 cancelled 结果而不是错误，因此此时保持登录界面不变即可。

```
# apps/mobile/.env.local
EXPO_PUBLIC_APP_SCHEME=supastack

# apps/web/.env.local — server side
AUTH_PASSKEY_ENABLED=true
MOBILE_ALLOWED_ORIGINS=
```


## 两侧允许列表保持一致

两侧都会校验回调目标：应用只接受 <scheme>://auth 以及已配置的生产来源，服务器则检查由 EXPO_PUBLIC_APP_SCHEME 和 MOBILE_ALLOWED_ORIGINS 构建的同一份列表。携带凭据、未知 scheme 或相似后缀的回调，在任何 Cookie 转移之前就会被拒绝。

生产环境中 MOBILE_ALLOWED_ORIGINS 为必填，且必须列出精确的非本地 HTTPS 来源 —— 不接受通配符。应用以打包形式分发，而服务器按请求读取自身环境，因此修改 scheme 或来源必须同时发布新的应用构建和服务器部署；只改一侧会让交接以失败关闭收场。


## 其他免密码方式

同一个登录界面还提供邮箱一次性验证码（先 requestEmailOtp 再 verifyEmailOtp），以及通过 signIn.social 加 callbackURL 的 Apple 或 Google 社交登录。服务器上 AUTH_PASSKEY_ENABLED=true 时会出现通行密钥；账户的通行密钥与两步验证设置仍在 Web 应用的“设置 → 安全”中。


## 验证与排障

在目标构建上演练冷启动回调、返回运行中的应用、取消的浏览器弹层以及过期会话。这些带类型的失败 —— passkeyUnavailable、browserFailed、untrustedCallback、missingCookie、malformedCookie、cookieStoreFailed —— 各自对应一种不同的断点；stateMismatch 表示 nonce 未能往返一致，该尝试被正确拒绝。

如果所有交接都被拒绝，请对比发布构建中的 EXPO_PUBLIC_APP_SCHEME 与服务器的 scheme 和 MOBILE_ALLOWED_ORIGINS —— 一侧重新部署而另一侧没有跟进时，这对值就会漂移。


## 下一篇

[移动端 API](https://supastack.dev/zh/docs/mobile/api.md)