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/web/apple-sign-in.md (or send Accept: text/markdown).
Adicionar o início de sessão com Apple
Registe uma App ID, uma Services ID e uma chave Sign in with Apple no portal Apple Developer e depois ligue o par de cliente à app.
Passo a passo para iniciantes
Pré-requisitos: a app web a correr em local (Online em 5 minutos), uma base de dados migrada para contas reais (Configurar a base de dados) e uma adesão ao Apple Developer Program — a mesma conta de 99 $ por ano que o guia de contas mobile cria, por isso conclua esse passo primeiro se ainda não o fez. Tudo o que está no portal de programador abaixo não custa nada extra.
Porque é importante: a revisão da App Store exige Sign in with Apple sempre que uma app iOS oferece início de sessão social de terceiros como Google ou GitHub — e é também um botão sólido de baixa fricção na web: os utilizadores Apple iniciam sessão com a conta que já têm nos seus dispositivos.
Terminologia rápida: uma App ID é o identificador registado da sua app (com.yourcompany.yourapp). Uma Services ID é um segundo identificador que a Apple emite para início de sessão web e de servidor — essa passa a ser o seu client ID. Uma return URL é o endereço exato para onde a Apple pode devolver um utilizador com sessão iniciada — o callback Better Auth do kit. Uma secret key é o ficheiro .p8 que a Apple lhe dá uma única vez; é você que o transforma no client secret.
1. Registe uma App ID com a capacidade Sign in with Apple. 2. Registe uma Services ID que aponta para ela e que guarda o seu domínio mais a return URL. 3. Crie uma chave Sign in with Apple e descarregue o ficheiro .p8. 4. Transforme a chave num JWT de client secret e defina os três valores env.
Uma limitação honesta: as return URL da Apple têm de ser endereços https:// absolutos num domínio registado — localhost e http simples são rejeitados, por isso o botão não pode ser exercido por completo num servidor local simples. Verifique no seu URL implementado, ou exponha o servidor local através de um túnel https (por exemplo cloudflared tunnel ou ngrok) e registe o domínio do túnel mais o seu callback durante os testes.
Registar a App ID
1. Abra developer.apple.com/account e inicie sessão com a conta que detém a adesão ao Developer Program.
2. Abra Certificates, Identifiers & Profiles → Identifiers e clique no botão azul +.
3. Selecione App IDs → Continue, mantenha o tipo em App → Continue.
4. Description: o nome do seu produto. Bundle ID: escolha Explicit e introduza a forma de domínio invertido com.yourcompany.yourapp — se lançar a app iOS, use exatamente o ios.bundleIdentifier de apps/mobile/app.json para que as duas plataformas partilhem uma única App ID.
5. Na lista de capacidades marque Sign in with Apple → Continue → Register.
Esperado: o identificador aparece na lista Identifiers com a capacidade Sign in with Apple ativada. Reutilize esta única App ID — a Services ID e a chave ligam-se ambas a ela como app primária.
Registar a Services ID e a return URL
1. De volta em Identifiers clique novamente em +, escolha Services IDs → Continue.
2. Description: algo como yourapp web sign-in. Identifier: outro nome de domínio invertido — a convenção é com.yourcompany.yourapp.web — deliberadamente diferente da App ID. Esta Services ID é o client ID que o servidor usa para o início de sessão web; copie-a exatamente e depois Continue → Register.
3. Selecione a nova Services ID na lista, marque Sign in with Apple e clique em Configure.
4. Na caixa de diálogo defina Primary App ID para a App ID da secção anterior. Em Website URLs adicione o seu domínio (por exemplo yourdomain.com), e em Return URLs adicione https://yourdomain.com/api/auth/callback/apple — esse caminho é o callback Better Auth do kit, {APP_URL}/api/auth/callback/apple. Save → Continue → Save.
Cada return URL tem de ser um endereço https:// absoluto num domínio registado: localhost, endereços IP simples e http são rejeitados. Para desenvolvimento local corra a app atrás de um túnel https, adicione o domínio do túnel à Services ID, registe https://<tunnel-domain>/api/auth/callback/apple e defina APP_URL para o URL do túnel durante os testes.
Esperado: a Services ID mostra Sign in with Apple → Enabled. Se o portal rejeitar o seu domínio, conclua primeiro a verificação de propriedade do domínio na página da conta.
Criar a chave Sign in with Apple
1. Abra Keys na barra lateral esquerda → +. Dê um nome à chave (por exemplo yourapp sign-in key), marque Sign in with Apple, clique em Configure, escolha a App ID como Primary App ID → Save → Continue → Register.
2. No ecrã de confirmação anote o Key ID e depois clique em Download — o ficheiro .p8 é oferecido exatamente uma vez. Se o perder, revogue a chave e crie outra; a Apple não guarda cópia.
3. Anote também o seu Team ID — está impresso no canto superior direito das páginas da conta de programador, junto ao nome da sua conta.
Esperado: tem agora três valores — o ficheiro .p8, um Key ID e o seu Team ID. Mantenha o ficheiro .p8 fora do Git: assina como a sua conta de programador.
Adicionar os valores à app
O kit espera exatamente as três linhas abaixo — o mesmo par clientId/clientSecret que cada provedor social usa. APPLE_CLIENT_ID é a Services ID (com.yourcompany.yourapp.web), não a App ID.
A Apple não emite um client secret estático, por isso APPLE_CLIENT_SECRET é um JWT que você próprio assina a partir do Team ID, do Key ID e da chave privada .p8 — a documentação do Better Auth inclui o pequeno script gerador para isso. Um secret assinado permanece válido no máximo seis meses: marque um lembrete para o regenerar e atualizar o valor env, porque o início de sessão falha no momento em que expira. Nunca cole o conteúdo do ficheiro .p8 nem o Key ID em bruto no env — só o JWT gerado pertence lá.
O client secret e o ficheiro .p8 são apenas do servidor: nunca em variáveis NEXT_PUBLIC_/EXPO_PUBLIC_ e nunca commitados — em produção defina-os através do secret store do seu hosting. Reinicie o servidor de desenvolvimento depois de editar; as alterações de env só são lidas no arranque.
# apps/web/.env.local
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.web # the Services ID, not the App ID
APPLE_CLIENT_SECRET=<JWT signed with Team ID + Key ID + .p8>Verificar e resolver problemas
Abra o seu APP_URL — um URL implementado ou o túnel https — em /auth, clique no botão Apple, inicie sessão com qualquer Apple ID (não precisa de ser a conta de programador) e confirme que regressa com sessão iniciada.
A maioria das falhas é uma de três confusões: Services ID vs App ID — o client ID tem de ser a Services ID para o início de sessão web; uma return URL que não corresponde — o callback tem de ser exatamente igual a uma Return URL registada, incluindo protocolo, domínio e caminho; ou um client secret expirado/inválido — regenere o JWT, que é apenas um token assinado, não o conteúdo do .p8.
Até AUTH_APPLE_ENABLED=true estar definido, a opção Apple em /auth permanece desativada — verifique os nomes env e reinicie. Ativar o flag sem APPLE_CLIENT_ID e APPLE_CLIENT_SECRET faz o arranque falhar e nomeia a variável em falta.
A app iOS chega a este mesmo backend — inclua Sign in with Apple nela para que a revisão da App Store aceite os outros botões sociais. O guia de contas mobile explica o que a revisão procura.
Para continuar a configuração, leia Adicionar os pagamentos com Stripe.