> ## 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.

# Guia de integração de autenticação: arquitetura e go-live

> Guia para integrar a Autenticação Didit em produção: telas hospedadas ou próprias, tokens, verificação no backend, sessões e go-live.

Este guia explica como uma integração de produção com a Autenticação Didit se encaixa, desde o primeiro redirecionamento até a lista de verificação para entrar em produção.
Comece pelo [guia de início rápido](https://docs.didit.me/pt-br/authentication/quickstart.md) se você ainda não autenticou nenhuma pessoa, e use os guias de início rápido das plataformas para o código de cada SDK.

## Arquitetura

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Quatro partes estão envolvidas:

| Parte | Responsável por |
| - | - |
| Seu app | Iniciar o login, manter o verificador PKCE e o `state`, guardar os tokens e enviar o token de acesso para o seu backend. Os SDKs fazem tudo isso. |
| Sua origem de login | `https://<slug>.auth.didit.me` (ou seu [domínio personalizado](https://docs.didit.me/pt-br/authentication/branding-and-custom-domain.md#domínio-personalizado)): as páginas hospedadas, o endpoint de token, a sessão, a descoberta e as chaves de assinatura. |
| Seu backend | Verificar o token de acesso em cada requisição protegida, checar a sessão antes de ações sensíveis e decidir o que a pessoa pode fazer. |
| Console da Didit e webhooks | Configuração, as pessoas e as respectivas sessões, eventos de login e os webhooks `auth.*` aos quais o seu servidor se inscreve. |

Nenhuma chave de API da Didit e nenhum segredo devem ficar no seu app: a chave publicável é pública, e a troca do código é protegida por PKCE, e não por um segredo do cliente.

## Páginas hospedadas ou suas próprias telas

Escolha onde as pessoas digitam o e-mail, a senha ou o código.
A configuração é `sign_in_ui` (`hosted` por padrão, ou `own`), e você pode alterá-la depois.

| | Páginas hospedadas (recomendado) | Suas próprias telas |
| - | - | - |
| O que você desenvolve | Um botão de login e uma página de callback. | Cada tela e cada etapa intermediária. |
| Métodos | Todos, incluindo links mágicos, SSO corporativo e passkeys. | Senha, código por e-mail, código por telefone, MFA e desafios de proteção por meio dos métodos sem interface dos SDKs. Links mágicos funcionam apenas nas páginas hospedadas. |
| Próximas etapas | Tratadas para você: MFA, cadastro de MFA, desafios de proteção e verificação no cadastro. | Suas telas tratam `mfa_required`, `mfa_enrollment_required`, `protection_required` e `verification_required`. Consulte [métodos de login](https://docs.didit.me/pt-br/authentication/sign-in-methods.md). |
| Marca | Seu logo, cores e textos da [identidade da marca](https://docs.didit.me/pt-br/authentication/branding-and-custom-domain.md). | Totalmente sua. |
| Configuração | URLs de redirecionamento. | URLs de redirecionamento, além da origem web em **Allowed origins**. |

As passkeys pertencem à origem de login da sua aplicação.
Os métodos de passkey dos SDKs funcionam apenas em páginas servidas a partir dessa origem. Por isso, nas suas próprias telas em outro domínio, direcione as pessoas para a página hospedada para usar passkeys.

## Escolha seu SDK

| Sua aplicação | Pacote | Onde os tokens ficam |
| - | - | - |
| Aplicação web de página única | [`@didit-protocol/auth`](https://docs.didit.me/pt-br/authentication/quickstarts/javascript) ou [`@didit-protocol/auth-react`](https://docs.didit.me/pt-br/authentication/quickstarts/react) | Armazenamento web ou memória no navegador. Mantenha uma política de segurança de conteúdo rigorosa. |
| Aplicação web renderizada no servidor | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/pt-br/authentication/quickstarts/nextjs) | Cookies HttpOnly definidos pelo seu servidor. A página nunca vê os tokens. |
| iOS | [`DiditAuth`](https://docs.didit.me/pt-br/authentication/quickstarts/ios) | O Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/pt-br/authentication/quickstarts/android) | Armazenamento protegido pelo Android Keystore. |
| React Native ou Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/pt-br/authentication/quickstarts/react-native) ou [`didit_auth`](https://docs.didit.me/pt-br/authentication/quickstarts/flutter) | O armazenamento protegido da plataforma, por meio dos módulos nativos. |
| Qualquer backend | [SDKs de servidor](https://docs.didit.me/pt-br/integration/server-sdks/overview.md), `verifyToken` de `@didit-protocol/auth/server`, ou qualquer biblioteca JWT | Nada para armazenar: ele verifica o token que recebe. |

Sem um SDK, implemente o fluxo de código de autorização com PKCE por conta própria: o [guia rápido de JavaScript](https://docs.didit.me/pt-br/authentication/quickstarts/javascript.md#sem-o-sdk) mostra o contrato completo.

## Proteja seu backend

Uma verificação de sessão apenas no frontend controla somente o que você exibe.
Seu backend toma todas as decisões a partir de um token verificado.

1. **Verifique o access token em cada requisição.** Confira a assinatura ES256 contra o JWKS do seu emissor e, em seguida, `iss`, `aud`, `exp` e `typ: at+jwt`, e rejeite um token cujo `act` não seja `null`, a menos que a rota aceite [agentes de IA](https://docs.didit.me/pt-br/authentication/agent-access.md). Veja [como verificar um token no seu servidor](https://docs.didit.me/pt-br/authentication/tokens-and-jwks.md#verificar-um-token-no-seu-servidor).
2. **Confira a sessão ativa antes de uma ação sensível.** Um access token continua válido até expirar, em até 5 minutos. `GET /session/` falha imediatamente quando a sessão foi revogada, ficou inativa ou expirou, quando a pessoa foi bloqueada ou quando a sessão deixa de atender à sua política de MFA. Veja [como verificar a sessão](https://docs.didit.me/pt-br/authentication/tokens-and-jwks.md#verificar-a-sessão).
3. **Peça um step-up quando a ação for arriscada.** Antes de um pagamento, de uma nova conta bancária ou de uma alteração de e-mail ou telefone, pergunte à Didit se a pessoa precisa verificar novamente, e aja somente com base em um step-up `approved` que o seu backend leu diretamente. Veja [step-up antes de ações sensíveis](https://docs.didit.me/pt-br/authentication/verified-identity.md#verificação-adicional-antes-de-ações-sensíveis).
4. **Obtenha o `vendor_data` a partir do token verificado**, nunca de um campo enviado pelo navegador, e use-o nas verificações e transações da pessoa.

## Sessões

| Evento | O que acontece |
| - | - |
| Login | Uma sessão começa. Sua duração é definida por `session_lifetime` (30 dias por padrão), e ela termina antes, após `idle_timeout` sem atividade (1 dia por padrão). |
| A cada poucos minutos | O SDK renova o token de acesso, que vale no máximo 5 minutos. O token de atualização é rotacionado: cada um funciona uma única vez. |
| Um token de atualização já usado é enviado novamente | A Didit trata isso como roubo e encerra a sessão. Faça uma renovação por vez em cada sessão. |
| Login em outro dispositivo | Com `multiple_sessions: false`, as outras sessões da pessoa são encerradas. |
| Redefinição de senha | Todas as sessões são encerradas quando `revoke_on_password_change` está ativado (o padrão). |
| Logout | `DELETE /session/` encerra a sessão, e seu app envia a pessoa para o seu `post_logout_redirect_uri`. |
| Sua equipe age | O console pode revogar uma sessão, encerrar todas as sessões da pessoa ou bloqueá-la. Consulte o [guia do console](https://docs.didit.me/pt-br/authentication/console.md#sign-ins-and-sessions). |

Altere as durações em **Authentication > Security and sessions**, ou pela API, em [configurações da aplicação](https://docs.didit.me/pt-br/authentication/overview.md#configurações-da-aplicação).

![Visualização Active sessions no Didit Business Console, listando sessões com login realizado, com dispositivo, localização, início, última atividade, término e um botão Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, com o botão Revoke em cada sessão.

## Aplicativos nativos

O Didit redireciona os usuários para um aplicativo nativo somente por redirecionamento HTTPS. Ele não aceita esquemas de URL personalizados.

* **iOS:** configure o redirecionamento como um domínio associado, com `webcredentials` no seu `apple-app-site-association`.
* **Android:** configure o redirecionamento como um App Link, com o seu `assetlinks.json`.
* Registre cada URL de redirecionamento em **Authentication > Security and sessions**, como um callback web.

Para chaves de acesso no seu aplicativo, registre os apps que compartilham as chaves de acesso da sua aplicação com `PUT native-apps/` na [API de gerenciamento de autenticação](https://docs.didit.me/pt-br/authentication/set-up-by-api.md).
Em seguida, o Didit lista esses apps no `apple-app-site-association` e no `assetlinks.json` que ele disponibiliza na sua origem de login.
`MANAGEMENT_BASE` é o endereço da API de gerenciamento da sua aplicação, e uma chave de API com o escopo `authentication` em **write** pode fazer a chamada.
A chamada substitui as duas listas, então envie as duas:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Campo | Regra |
| - | - |
| `ios_app_ids` | Até 10 entradas, cada uma com o Team ID e o identificador do bundle, por exemplo `ABCDE12345.com.example.app`. |
| `android_apps` | Até 10 apps, cada um com seu `package_name` e de 1 a 5 impressões digitais SHA-256 do certificado de assinatura. |

Os guias de início rápido para [iOS](https://docs.didit.me/pt-br/authentication/quickstarts/ios.md) e [Android](https://docs.didit.me/pt-br/authentication/quickstarts/android.md) mostram o lado do app.

## Conecte a verificação de identidade e o monitoramento de transações

Cada pessoa tem um único valor `vendor_data`, presente nos seus tokens e na sua sessão.
Use-o como `vendor_data` ao [criar uma sessão de verificação](https://docs.didit.me/pt-br/sessions-api/create-session.md) ou [enviar uma transação](https://docs.didit.me/pt-br/transaction-monitoring/transactions.md), e o console mostra os logins, as verificações e as transações da mesma pessoa.

* Para verificar pessoas no cadastro ou novamente antes de um repasse, sem criar um fluxo de verificação próprio, use a [identidade verificada](https://docs.didit.me/pt-br/authentication/verified-identity.md).
* Os eventos de login chegam automaticamente às [regras de eventos](https://docs.didit.me/pt-br/transaction-monitoring/event-rules.md) e às visualizações de fraude. Não envie seus próprios eventos `auth.login` para os mesmos logins.
* Um login bem-sucedido nunca aprova uma verificação ou uma transação: trate a decisão de cada produto separadamente.

Veja [como manter a mesma pessoa em todos os produtos](https://docs.didit.me/pt-br/authentication/overview.md#manter-a-mesma-pessoa-entre-produtos).

## Receber eventos de login

Assine um [destino do webhook](https://docs.didit.me/pt-br/integration/webhooks.md) para os tipos `auth.*` de que você precisar, como `auth.new_device` ou `auth.account_locked`.
Elimine duplicatas com base em `auth_event.event_id` e verifique a assinatura, como em qualquer webhook da Didit.
Consulte [eventos e webhooks](https://docs.didit.me/pt-br/authentication/events-and-webhooks.md) para ver todos os tipos e seus payloads.

## Mover usuários existentes

Se seus usuários já têm contas em outra plataforma de identidade ou no seu próprio banco de dados, [importe-os](https://docs.didit.me/pt-br/authentication/migration.md) antes de trocar o login.
Importe os hashes de senha quando a origem os fornecer, mantenha os vínculos com redes sociais e mantenha seus próprios IDs de usuário como `external_id`, que passam a ser o `vendor_data` deles.
Nada muda para eles até que você troque o seu app para a Didit.

## Checklist para colocar em produção

1. A autenticação está ativada na sua aplicação Live, na página **Products**.
2. As URLs de redirecionamento `https://` de produção e as origens permitidas estão cadastradas na aplicação Live. Uma aplicação Live não aceita endereços `http://`.
3. Cada método de login social usa o ID do cliente e o segredo do seu próprio aplicativo: as credenciais de teste da Didit funcionam apenas no Sandbox.
4. Sua configuração de produção tem a chave publicável Live (`pk_live_`) e o seu emissor Live.
5. Sua política de MFA, a duração da sessão, o tempo limite por inatividade, o tamanho da senha e a política de cadastro estão como você deseja. Consulte [configurações da aplicação](https://docs.didit.me/pt-br/authentication/overview.md#configurações-da-aplicação).
6. A [proteção contra bots](https://docs.didit.me/pt-br/authentication/bot-protection.md) está ativada, com a verificação de senhas vazadas.
7. Seu backend verifica cada token de acesso e chama `GET /session/` antes de ações sensíveis.
8. Sua marca, os textos das páginas e os links para termos e política de privacidade estão configurados. Se você planeja usar um [domínio personalizado](https://docs.didit.me/pt-br/authentication/branding-and-custom-domain.md#domínio-personalizado), ative-o antes que as pessoas comecem a adicionar chaves de acesso.
9. Seu destino de webhook está inscrito nos tipos `auth.*` que você trata.
10. Você testou cadastro, login de usuário recorrente, cancelamento, recuperação de senha, MFA, expiração da sessão, encerramento da sessão e uma sessão revogada na aplicação Live.

## Troubleshooting

| Sintoma | Causa e correção |
| - | - |
| Todas as rotas de runtime respondem `404` | A autenticação está desativada para a aplicação, ou o endereço mistura uma origem de sandbox com uma de produção. Ative-a na página **Products** e use a origem indicada pela sua chave publicável. |
| A página de login responde `400` e pede que você registre um endereço, ou `POST /authorize/` responde `invalid_redirect_uri` | O `redirect_uri` não está registrado exatamente: esquema, host, porta, caminho e query devem coincidir caractere por caractere. Veja [URLs de redirecionamento](https://docs.didit.me/pt-br/authentication/overview.md#urls-de-redirecionamento). |
| Uma chamada do navegador à sua origem de login responde `403` com `origin_not_allowed` | Sua origem web não está em **Allowed origins**. Adicione-a sem caminho e sem barra final. |
| `POST /token/` responde `invalid_grant` | O código já foi usado, tem mais de 60 segundos, ou foi enviado com outro verificador PKCE ou outro `redirect_uri`. Em uma atualização, o token de atualização já foi usado, o que encerra a sessão. Inicie o login novamente. |
| Um login com senha responde `invalid_credentials` mesmo com a senha correta | O e-mail não foi verificado, ou a conta está bloqueada ou impedida de acessar. A Didit dá a mesma resposta de propósito. Verifique a pessoa em **Users**. |
| `GET /session/` responde `401` | A sessão foi revogada, ficou inativa ou expirou, a pessoa foi bloqueada, o token foi substituído durante uma atualização, ou a sessão não atende mais à sua política de MFA. Atualize o token ou faça o login da pessoa novamente. |
| Adicionar uma passkey ou um autenticador responde `403 reauthentication_required` | Essas operações exigem uma sessão criada nos últimos 5 minutos. Primeiro, faça o login da pessoa novamente. |
| Um código por telefone responde `503 delivery_unavailable` | O código não pôde ser entregue. Permita que a pessoa tente novamente ou ofereça outro método. |
| Uma chamada responde `429` | Você atingiu um limite de requisições. Tente novamente após o tempo indicado em `Retry-After`. Veja [limites de requisições](https://docs.didit.me/pt-br/authentication/bot-protection.md#limites-de-requisições). |
| Uma chamada de configuração com uma chave de API responde `409 product_disabled` | A autenticação está desativada para a aplicação. Uma pessoa a ativa no console. |
| Uma chamada responde `403 plan_required` | O recurso, como funções personalizadas ou links de configuração de SSO corporativo, exige o plano Scale ou Enterprise. Aplicações sandbox têm o recurso em qualquer plano. |
| Os tokens falham depois que você ativou um domínio personalizado | O emissor e a chave publicável mudaram. Copie a nova chave para o seu app e atualize o emissor que o seu backend verifica. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.