Métodos de login: passkeys, códigos, social e SSO

Ative um método com PUT methods/{name}/ e {"enabled": true} na API de gerenciamento de autenticação da sua aplicação, ou pelo console. O login hospedado mostra apenas os métodos que você ativou. Cada chamada JSON abaixo começa com uma transaction obtida em POST authorize/. Essa transação dura 10 minutos. Um login bem-sucedido retorna {code, redirect_uri, state}. Troque o código em POST token/ em até 60 segundos (consulte tokens e JWKS). Em vez de um código, uma chamada de login pode retornar uma destas etapas. Conclua a etapa e você receberá o código.

​

Senha

POST password/ recebe transaction, email e password.

• A senha deve atender ao seu password_min_length (8, 10, 12 ou 14 caracteres; 10 por padrão). Senhas comuns e totalmente numéricas são rejeitadas com password_policy. Quando a verificação de senhas vazadas está ativada, uma senha sabidamente vazada é rejeitada com password_breached.
• Somente pessoas com e-mail verificado podem fazer login com senha.
• Senha incorreta, e-mail desconhecido, e-mail não verificado, conta travada e conta bloqueada recebem todos a mesma resposta: 400 {"error": "invalid_credentials"}. Sua UI não consegue saber qual foi o caso, e um invasor também não.

​

Cadastro

O cadastro verifica o e-mail primeiro. Chame POST email/start/ com purpose: "signup", email e password e, em seguida, POST email/complete/ com o código. A conta é criada com o e-mail já verificado.

• signup_policy define quem pode se cadastrar: anyone, invited (somente com um link de convite) ou allowed_domains.
• Com allow_subaddresses: false (o padrão), um endereço com + na parte local é rejeitado.
• Quando a identidade visual da sua marca inclui links para os termos ou a política de privacidade, o formulário de cadastro hospedado pede que a pessoa os aceite.

​

Código por e-mail

POST email/start/ recebe transaction, purpose (login ou signup) e email, e retorna 202 {challenge, expires_in: 600}. A pessoa recebe um código de 6 dígitos que dura 10 minutos. POST email/complete/ recebe transaction, purpose, challenge e code. Você tem 5 tentativas; depois disso, a pessoa precisa solicitar um novo código. A página hospedada oferece um novo código após 30 segundos. Um código de login para um endereço sem conta cria uma conta quando o seu signup_policy permite. Isso é cadastro sem senha.

​

Link mágico

A página hospedada envia um link de login que dura 15 minutos. Ele permanece vinculado à transação PKCE original, então o link funciona apenas no fluxo que o iniciou. A pessoa confirma o login na página que o link abre. Não há endpoint JSON para links mágicos.

​

Código por telefone

POST phone/start/ recebe transaction, phone e um channel opcional (sms, o padrão, ou whatsapp). O número é normalizado para E.164. Retorna 202 {challenge, expires_in: 600}. POST phone/complete/ recebe transaction, challenge e o code de 6 dígitos. Você tem 5 tentativas.

• Os códigos por telefone são entregues pelo serviço de verificação por telefone da Didit. Ative o método com o workflow_id de um fluxo que contenha a verificação por telefone.
• O primeiro login por telefone só cria uma conta quando signup_policy é anyone.
• Se a entrega falhar, a chamada retorna 503 {"error": "delivery_unavailable"}.

​

Passkeys

As passkeys usam WebAuthn. A parte confiável é a origem de login da sua aplicação. A Didit solicita uma credencial detectável (resident key) e sempre exige a verificação do usuário, como impressão digital, rosto ou PIN do dispositivo. A Didit não solicita attestation.

• O desafio de uma passkey dura 5 minutos.
• Adicionar uma passkey exige uma sessão criada nos últimos 5 minutos. Caso contrário, a chamada retorna 403 {"error": "reauthentication_required"}. Peça à pessoa para fazer login novamente primeiro.
• Um login com passkey conta como autenticação multifator.
• Após o cadastro, a página hospedada oferece a opção de adicionar uma passkey (passkeys/setup/begin/ e passkeys/setup/complete/).
• Apps Android registrados na aplicação podem usar as mesmas passkeys.

​

Login social

O login com Google, Microsoft, Apple e GitHub usa as credenciais do seu próprio app OAuth, definidas com PUT methods/{provider}/ e credentials: {client_id, client_secret}. O callback do provedor fica na sua origem de login. Na primeira vez que alguém faz login com um provedor, a pessoa também comprova que é titular do endereço de e-mail com um código (POST social/email/start/ e POST social/email/verify/). Os logins seguintes com esse provedor pulam essa etapa. O GitHub não consegue comprovar um login recente, por isso não é oferecido quando você envia prompt=login ou max_age.

​

SSO da organização

O SSO da organização permite que a empresa de um cliente faça login pelo próprio provedor de identidade SAML ou OIDC. Configure-o por organização cliente em organizations/{id}/sso/ com protocol (saml ou oidc), enabled e config.

• Você pode enviar à equipe de TI do cliente um link de configuração válido por 7 dias.
• Os metadados do seu provedor de serviços SAML são publicados em {origin}/sso/saml/metadata/.
• O login hospedado encontra a conexão pelo domínio do e-mail verificado da pessoa ou por organization=<slug> na URL de login.

​

Didit ID Wallet

Pessoas que já fizeram uma verificação pela Didit podem fazer login com a Didit ID Wallet. Esse método está sempre ativado. O verified_identity da sessão passa então a conter o que a pessoa escolheu compartilhar.

​

MFA

O segundo fator é um app autenticador (TOTP) com códigos de recuperação, ou uma passkey.

• mfa_policy define quem deve usar MFA: optional, everyone ou organization_admins (o padrão). Quem cadastrou um autenticador deve sempre usá-lo.
• Para cadastrar um autenticador, chame POST mfa/enroll/ com uma sessão recente (criada há no máximo 5 minutos). A chamada retorna {challenge, uri}; exiba o uri como QR code. Em seguida, envie o primeiro código para POST mfa/confirm/. A resposta contém 10 códigos de recuperação de uso único. Exiba-os uma única vez.
• No login, envie um código TOTP ou de recuperação para POST mfa/complete/ com o challenge. Você tem 5 tentativas. Para usar uma passkey, chame POST mfa/passkey/begin/ e POST mfa/passkey/complete/.
• Os códigos usam intervalos de 30 segundos. Um código que já foi aceito não pode ser usado novamente.
• Códigos por SMS e e-mail não estão disponíveis como segundo fator.

​

Esquecimento e redefinição de senha

POST password-reset/start/ recebe email e retorna 202 {"status": "sent", "expires_in": 1800}. A resposta é a mesma, independentemente de o endereço ter uma conta ou não. O link de redefinição vale por 30 minutos. POST password-reset/complete/ recebe token e password e retorna {"status": "password_changed"}. Além disso, a chamada:

• remove o bloqueio de acesso,
• encerra todas as sessões quando revoke_on_password_change está ativado (o padrão),
• invalida outros códigos e links pendentes dessa pessoa.

​

Convites

Com signup_policy: "invited", só pessoas convidadas podem se cadastrar. Um link de convite vale por 7 dias e abre a página hospedada /invite. Continue com tokens e JWKS ou leia sobre proteção contra bots para bloqueios e desafios.