For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/mobile/passkeys.md (or send Accept: text/markdown).
Início de sessão com passkey
Início de sessão sem palavra-passe através de um handoff pelo browser que devolve a sessão à app.
Como funciona o handoff
O início de sessão com passkey começa na app e termina no browser do sistema. A app abre {API URL}/auth?mobile_callback=<deep link> através de WebBrowser.openAuthSessionAsync; depois de a página web concluir qualquer método de início de sessão, chama GET /api/auth/mobile-handoff, que redireciona de volta para <scheme>://auth/callback trazendo o cookie de sessão e um nonce de state.
Cada tentativa gera um nonce novo que tem de fazer a viagem de ida e volta inalterado — um parâmetro state diferente é rejeitado como stateMismatch, por isso um callback velho ou forjado não consegue injetar uma sessão. O cookie devolvido junta-se ao mesmo jar do SecureStore que o cliente Better Auth Expo usa (supastack.auth_cookie); depois a store de sessão é notificada e a app com sessão iniciada renderiza.
Um sheet de browser dispensado resolve-se num resultado silencioso cancelled em vez de um erro, por isso mantém o ecrã de início de sessão inalterado quando isso acontece.
# apps/mobile/.env.local
EXPO_PUBLIC_APP_SCHEME=supastack
# apps/web/.env.local — server side
AUTH_PASSKEY_ENABLED=true
MOBILE_ALLOWED_ORIGINS=Mantém a allow-list idêntica dos dois lados
Os dois lados validam o destino do callback: a app aceita apenas <scheme>://auth mais as suas origens de produção configuradas, e o servidor verifica a mesma lista construída a partir de EXPO_PUBLIC_APP_SCHEME e MOBILE_ALLOWED_ORIGINS. Callbacks com credenciais, esquemas desconhecidos ou sufixos parecidos são rejeitados antes de qualquer cookie se mover.
Em produção MOBILE_ALLOWED_ORIGINS é obrigatória e tem de listar origens HTTPS exatas e não-locais — wildcards não são aceites. A app sai empacotada enquanto o servidor lê o seu ambiente por pedido, por isso uma mudança de scheme ou origem exige um novo build da app e um deploy do servidor; mudar só um lado faz os handoffs falhar fechado.
Os outros métodos sem palavra-passe
O mesmo ecrã de início de sessão oferece códigos de uso único por email (requestEmailOtp seguido de verifyEmailOtp) e início de sessão social Apple ou Google através de signIn.social com um callbackURL. As passkeys aparecem quando AUTH_PASSKEY_ENABLED=true no servidor; a configuração de passkey e de dois fatores de uma conta continua na app web em Configurações → Segurança.
Verificação e resolução de problemas
Exercita um callback de arranque a frio, um regresso a uma app em execução, um sheet de browser cancelado e uma sessão expirada no build pretendido. As falhas tipadas — passkeyUnavailable, browserFailed, untrustedCallback, missingCookie, malformedCookie, cookieStoreFailed — descrevem cada uma uma quebra distinta; stateMismatch significa que o nonce não fez a viagem de ida e volta e a tentativa foi recusada corretamente.
Se todos os handoffs forem rejeitados, compara o EXPO_PUBLIC_APP_SCHEME do build publicado com o scheme e o MOBILE_ALLOWED_ORIGINS do servidor — o par desalinha quando um lado foi redesenvolvido sem o outro.