> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Início de sessão: chaves, códigos, redes sociais, SSO > Configure no Didit o início de sessão por palavra-passe, código, ligação mágica, chave de acesso, redes sociais ou SSO, com MFA e recuperação de palavra-passe. > [!WARNING] > > A autenticação é nova. A página de início de sessão alojada executa todos os métodos desta página. Os endpoints JSON listados aqui destinam-se a equipas que criam os seus próprios ecrãs de início de sessão (`sign_in_ui: "own"`). Ative um método com `PUT methods/{name}/` e `{"enabled": true}` na API de gestão de autenticação da sua aplicação, ou na consola. O início de sessão alojado mostra apenas os métodos que ativou. | Método | Nome | Configuração | | - | - | - | | Palavra-passe | `password` | Também necessária para o registo por e-mail com palavra-passe. | | Código por e-mail | `code` | Nenhuma. | | Ligação mágica | `magic` | Nenhuma. Apenas páginas alojadas. | | Código por telefone | `phone` | Envie o `workflow_id` de um fluxo de verificação de telefone. | | Passkey | `passkey` | Nenhuma. | | Início de sessão social | `google`, `microsoft`, `apple`, `github` | O seu próprio `client_id` e `client_secret`. As aplicações sandbox podem usar as aplicações de teste da Didit (`credential_source: "didit_test"`). | | SSO de organização | `sso` | Uma ligação SAML ou OIDC por cada organização cliente. | | Didit ID Wallet | `wallet` | Sempre ativa. Não pode ser desligada. | Cada chamada JSON abaixo começa com uma `transaction` de `POST authorize/`. Essa transação dura 10 minutos. Um início de sessão bem-sucedido devolve `{code, redirect_uri, state}`. Troque o código em `POST token/` no prazo de 60 segundos (ver [tokens e JWKS](https://docs.didit.me/pt/authentication/tokens-and-jwks.md)). Em vez de um código, uma chamada de início de sessão pode devolver um destes passos. Conclua o passo e receberá depois o código. | Resposta | Próximo passo | | - | - | | `mfa_required` com `challenge` e `factors` | Envie um código TOTP ou de recuperação, ou use uma passkey (ver [MFA](#mfa)). | | `mfa_enrollment_required` com `challenge` e `uri` | A política de MFA exige um autenticador. Registe-o com `POST mfa/setup/`. | | `protection_required` com `challenge` e `methods` | Uma política de [proteção contra bots](https://docs.didit.me/pt/authentication/bot-protection.md) pede uma prova adicional. | | `verification_required` com `verification_url` | As suas definições de verificação exigem uma prova de vida ou uma verificação de identidade no registo ou no início de sessão. Encaminhe a pessoa para `verification_url` (válido durante 30 minutos); o código é emitido após uma verificação aprovada. | ## Palavra-passe `POST password/` recebe `transaction`, `email` e `password`. * Uma palavra-passe tem de cumprir o `password_min_length` definido (8, 10, 12 ou 14 caracteres; 10 por predefinição). Palavras-passe comuns e apenas numéricas são rejeitadas com `password_policy`. Quando a [verificação de palavras-passe comprometidas](https://docs.didit.me/pt/authentication/bot-protection.md#palavras-passe-comprometidas) está ativa, uma palavra-passe conhecida como comprometida é rejeitada com `password_breached`. * Só as pessoas com um e-mail verificado podem iniciar sessão com palavra-passe. * Uma palavra-passe errada, um e-mail desconhecido, um e-mail não verificado, uma conta bloqueada e uma conta bloqueada recebem todos a mesma resposta: `400 {"error": "invalid_credentials"}`. A sua interface não consegue distinguir qual foi, e um atacante também não. ### Registo O registo verifica primeiro o e-mail. Chame `POST email/start/` com `purpose: "signup"`, `email` e `password`, e depois `POST email/complete/` com o código. A conta é criada com um e-mail verificado. * `signup_policy` define quem pode fazer o registo: `anyone`, `invited` (apenas com uma ligação de convite) ou `allowed_domains`. * Com `allow_subaddresses: false` (a predefinição), um endereço com `+` na parte local é rejeitado. * Quando a sua identidade visual define ligações para os termos ou para a política de privacidade, o formulário de registo alojado pede à pessoa que as aceite. ## Código por e-mail `POST email/start/` recebe `transaction`, `purpose` (`login` ou `signup`) e `email`, e devolve `202 {challenge, expires_in: 600}`. A pessoa recebe um código de 6 dígitos válido durante 10 minutos. `POST email/complete/` recebe `transaction`, `purpose`, `challenge` e `code`. Há 5 tentativas; depois disso, a pessoa tem de pedir um novo código. A página alojada oferece um novo código após 30 segundos. Um código de início de sessão para um endereço sem conta cria uma conta quando o seu `signup_policy` o permitir. Isto é registo sem palavra-passe. ## Ligação mágica A página alojada envia uma ligação de início de sessão válida durante 15 minutos. Fica associada à transação PKCE original, pelo que a ligação só funciona no fluxo que a iniciou. A pessoa confirma o início de sessão na página que a ligação abre. Não existe endpoint JSON para ligações mágicas. ## Código por telefone `POST phone/start/` recebe `transaction`, `phone` e um `channel` opcional (`sms`, a predefinição, ou `whatsapp`). O número é normalizado para E.164. Devolve `202 {challenge, expires_in: 600}`. `POST phone/complete/` recebe `transaction`, `challenge` e o `code` de 6 dígitos. Há 5 tentativas. * Os códigos por telefone são enviados através da Verificação de telefone da Didit. Ative o método com o `workflow_id` de um fluxo que contenha verificação de telefone. * Um primeiro início de sessão por telefone só cria uma conta quando `signup_policy` for `anyone`. * Se o envio falhar, a chamada devolve `503 {"error": "delivery_unavailable"}`. ## Passkeys As passkeys usam WebAuthn. A parte confiante (relying party) é a origem de início de sessão da sua aplicação. A Didit pede uma credencial detetável (resident key) e exige sempre verificação do utilizador, como impressão digital, rosto ou PIN do dispositivo. A Didit não pede atestação. | Chamada | Corpo | Resultado | | - | - | - | | `POST passkeys/begin/` | `{transaction}` | `{challenge, options}` para `navigator.credentials.get()`. Não é enviada nenhuma lista de credenciais, por isso o navegador oferece todas as passkeys da sua origem. | | `POST passkeys/complete/` | `{challenge, credential}` | Um código de início de sessão, ou um próximo passo. | | `POST passkeys/register/` | Vazio, com `Authorization: Bearer ` | Opções para `navigator.credentials.create()`. | | `POST passkeys/confirm/` | `{challenge, credential}`, com o mesmo token | `{id}` da nova passkey. | * Um desafio de passkey dura 5 minutos. * Adicionar uma passkey exige uma sessão criada nos últimos 5 minutos. Caso contrário, a chamada devolve `403 {"error": "reauthentication_required"}`. Peça primeiro à pessoa que volte a iniciar sessão. * Um início de sessão com passkey conta como autenticação multifator. * Após o registo, a página alojada oferece adicionar uma passkey (`passkeys/setup/begin/` e `passkeys/setup/complete/`). * As aplicações Android registadas na sua aplicação podem usar as mesmas passkeys. ## Início de sessão social O Google, a Microsoft, a Apple e o GitHub usam as suas próprias credenciais de aplicação OAuth, definidas com `PUT methods/{provider}/` e `credentials: {client_id, client_secret}`. O URL de retorno do fornecedor encontra-se na origem de início de sessão. Na primeira vez que alguém inicia sessão com um fornecedor, 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 inícios de sessão seguintes com esse fornecedor saltam este passo. O GitHub não consegue comprovar um início de sessão recente, por isso não é disponibilizado quando envia `prompt=login` ou `max_age`. ## SSO da organização O SSO da organização permite que a empresa de um cliente inicie sessão através do seu próprio fornecedor de identidade SAML ou OIDC. Configure-o por organização de cliente em `organizations/{id}/sso/` com `protocol` (`saml` ou `oidc`), `enabled` e `config`. * Pode enviar à equipa de TI do cliente uma ligação de configuração válida durante 7 dias. * Os metadados do seu fornecedor de serviço SAML são publicados em `{origin}/sso/saml/metadata/`. * O início de sessão alojado encontra a ligação a partir do domínio de e-mail verificado da pessoa, ou a partir de `organization=` no URL de início de sessão. ## Didit ID Wallet As pessoas que já verificaram a sua identidade com a Didit podem iniciar sessão com a sua Didit ID Wallet. Este método está sempre ativado. O `verified_identity` da sessão contém então o que a pessoa escolheu partilhar. ## MFA O segundo fator é uma aplicação de autenticação (TOTP) com códigos de recuperação, ou uma passkey. * `mfa_policy` decide quem tem de usar MFA: `optional`, `everyone` ou `organization_admins` (o valor predefinido). Quem tiver registado uma aplicação de autenticação tem sempre de a usar. * Para registar uma aplicação de autenticação, chame `POST mfa/enroll/` com uma sessão recente (criada há menos de 5 minutos). A resposta devolve `{challenge, uri}`; apresente o `uri` como código QR. Depois envie o primeiro código para `POST mfa/confirm/`. A resposta contém 10 códigos de recuperação de utilização única. Mostre-os uma única vez. * No início de sessão, envie um código TOTP ou um código de recuperação para `POST mfa/complete/` com o `challenge`. Tem 5 tentativas. Para usar uma passkey, chame `POST mfa/passkey/begin/` e `POST mfa/passkey/complete/`. * Os códigos usam passos de 30 segundos. Um código já aceite não pode voltar a ser usado. * Os códigos por SMS e por e-mail não estão disponíveis como segundo fator. ## Recuperação e reposição da palavra-passe `POST password-reset/start/` recebe `email` e devolve `202 {"status": "sent", "expires_in": 1800}`. A resposta é a mesma, tenha ou não conta associada ao endereço. A ligação de reposição é válida durante 30 minutos. `POST password-reset/complete/` recebe `token` e `password` e devolve `{"status": "password_changed"}`. Além disso: * remove um bloqueio, * termina todas as sessões quando `revoke_on_password_change` está ativado (o valor predefinido), * invalida os outros códigos e ligações pendentes dessa pessoa. ## Convites Com `signup_policy: "invited"`, só as pessoas convidadas podem criar conta. Uma ligação de convite é válida durante 7 dias e abre a página `/invite` alojada. Continue com [tokens e JWKS](https://docs.didit.me/pt/authentication/tokens-and-jwks.md), ou leia [proteção contra bots](https://docs.didit.me/pt/authentication/bot-protection.md) para bloqueios e desafios. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.