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

# Configurar a Autenticação da Didit pela API

> Ative métodos de login, configurações, marca e proteção na Didit pelo seu código, com permissão aprovada pelo dono ou chave de API de autenticação.

Didit Authentication permite que você habilite métodos de login e leia as configurações da sua aplicação pela API. Use uma concessão aprovada pelo proprietário da aplicação ou uma chave de API com o escopo `authentication`.

> [!WARNING]
>
> O recurso Authentication é novo. Configure um método primeiro em uma aplicação sandbox e depois na sua aplicação de produção.

Cada chamada abaixo é enviada à API de gestão de autenticação da sua aplicação. `MANAGEMENT_BASE` é:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

As mesmas rotas são descritas pelo `openapi-authentication.json`, na tag `Setup`; os SDKs de servidor são regenerados a partir desse arquivo.

## Qual credencial usar

Qualquer uma das três credenciais funciona, e cada uma se limita ao que o titular aprovou.

| Credencial | Enviada como | O que pode fazer |
| - | - | - |
| Chave de API nomeada com o escopo `authentication` | `x-api-key: <key>` | Configura a própria aplicação e a lê. Uma chave com `read` só pode ler a configuração; `write` pode lê-la e alterá-la. |
| Concessão aprovada pelo titular com `didit:management` | `Authorization: Bearer <access_token>` | Configura as aplicações das organizações aprovadas no consentimento, dentro da função da pessoa. |
| Sessão do console | `Authorization: Bearer <console session token>` | Lê ou altera as configurações de acordo com o vínculo da pessoa com a organização e sua função. As visualizações de usuário final também exigem uma sessão do console e as permissões adequadas. |

Essas credenciais são recusadas com `403` em todas as rotas de configuração, independentemente do que a requisição pede:

* O **segredo principal** da aplicação.
* Um token obtido em `POST /programmatic/login`, que é gerado para a aplicação e não para o console.
* Uma chave **sem** o escopo `authentication`, inclusive uma chave criada com todos os recursos no nível mais alto: essas chaves aparecem como acesso total, mantêm `scopes` vazio e não são aceitas nessas rotas.
* Uma chave de **outra aplicação**, uma concessão limitada a `didit:verification` e uma concessão aprovada para outra organização.

Uma requisição sem nenhuma credencial recebe `401`. Uma concessão ou uma chave mantém os próprios limites além desses: a concessão, seus escopos, suas organizações e a função da pessoa; a chave, seus escopos, sua lista de IPs permitidos e sua validade.

## Aprovar acesso

### Com uma chave de API nomeada

Abra **Developers -> API keys** no [Business Console](https://business.didit.me) e crie uma chave para a aplicação que você está configurando. Dê à chave o recurso `authentication` com acesso de **leitura** ou de **escrita**: a leitura cobre todas as chamadas que leem a configuração (`GET`); a escrita cobre todas as chamadas que alteram a configuração (`POST`, `PUT`, `PATCH`, `DELETE`) e também leem a configuração. Veja [Chaves de API](https://docs.didit.me/pt-br/console/api-keys.md) para expiração, listas de IP permitidos e rotação. Uma chave pertence a uma aplicação e funciona somente para ela.

### Por meio de uma conexão MCP

Um agente conectado ao servidor MCP da Didit usa a concessão que o proprietário aprovou na tela de consentimento, com `didit:management`. Veja [Autenticação MCP](https://docs.didit.me/pt-br/integration/mcp/authentication.md#entrar-com-a-didit).

### Para um proprietário sem senha

A concessão por código de dispositivo ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) permite que um proprietário que faz login com Google, com uma chave de acesso ou com um código enviado por e-mail aprove o mesmo acesso a partir de qualquer navegador, sem digitar uma senha. Veja [Fazer login sem navegador](https://docs.didit.me/pt-br/integration/mcp/authentication.md#entrar-sem-navegador-código-de-dispositivo).

## Ativar código por e-mail

`PUT methods/{name}/` aceita `enabled`, e nenhum outro campo para um método que não exige credenciais.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

A resposta mostra o método como ele está agora:

```json theme={null}
{"name": "code", "enabled": true}
```

Ao ler a configuração de volta, a entrada de código por e-mail inclui `credential_source: null`. Métodos que estão sempre ativos não podem ser desativados: essa requisição responde `{"enabled": "always_on"}`.

## Ativar o Google

Um método social usa as credenciais do seu próprio app OAuth ou o app de teste da Didit em uma aplicação sandbox.

### Com o seu próprio app do Google

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Registre o `callback_uri` retornado na resposta no seu provedor. O segredo é somente de escrita: nenhuma resposta o retorna, e `client_id` é a única parte que você pode ler de volta. Ativar um método sem credenciais, quando nenhuma foi armazenada antes, responde com `{"credentials": "required"}`.

### Com o app de teste da Didit (`didit_test`)

Uma **aplicação sandbox** pode usar os apps sociais da própria Didit em vez dos seus, o que basta para concluir a configuração e comprovar que ela funciona:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` cobre **Google, Microsoft, Apple e GitHub**, somente em aplicações sandbox:

| Resposta | Quando |
| - | - |
| `{"credential_source": "sandbox_only"}` | A aplicação está em produção. Apps de teste nunca processam logins em produção. |
| `{"credential_source": "unavailable"}` | A implantação não tem app de teste para esse provedor, então o método permanece desativado. |
| `200` com `configured: true` | O app de teste disponibiliza o método, e o login hospedado o oferece. |

A requisição `GET` à configuração informa os provedores que um app de teste pode atender para esta aplicação em `didit_test_credentials`, que é `false` para todos os quatro em uma aplicação de produção.

## Consultar a configuração

`GET` em `MANAGEMENT_BASE` retorna a configuração completa: cada método com `enabled` e `credential_source`, além das URLs de retorno, das regras de sessão e da política de cadastro.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Os métodos desativados também aparecem na lista, então um único `GET` mostra o que está ativo e o que não está. `enabled` no topo é `false` quando a Autenticação está desativada para a aplicação. Qualquer alteração de configuração feita com uma concessão de gerenciamento ou com uma chave nomeada retorna `409` com `{"detail": "product_disabled"}`, e nada é gravado. Nenhuma chamada de configuração ativa a Autenticação: uma pessoa a ativa para a aplicação no console, e suas chamadas passam a funcionar a partir daí.

## O restante da configuração

| Rota, em `MANAGEMENT_BASE` | Métodos | O que contém |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Acesso de agentes, organizações, a política de MFA, a função padrão de membro e os eventos de webhook desativados |
| `onboarding/` | `GET`, `PATCH` | Quais etapas da configuração foram concluídas e se as pessoas fazem login na página hospedada ou nas suas próprias telas |
| `branding/` | `GET`, `PATCH` | Os textos das páginas hospedadas e os links legais (o logo e as cores vêm de Personalização) |
| `protection/` | `GET`, `PATCH` | As políticas de proteção contra bots ([proteção contra bots](https://docs.didit.me/pt-br/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | O nível de verificação do cadastro, as regras de verificação adicional e os claims do token |
| `emails/`, `emails/{key}/` | `GET` | Os e-mails de login que esta aplicação envia, e uma prévia renderizada |
| `domain/` | `GET`, `PUT`, `DELETE` | A origem hospedada e o domínio de login personalizado |
| `domain/verify/`, `domain/activate/` | `POST` | Verifica o DNS e o certificado do domínio e, em seguida, o torna a origem canônica |
| `native-apps/` | `GET`, `PUT` | Os aplicativos iOS e Android que compartilham as passkeys da aplicação |

Uma permissão ou uma chave tem acesso à configuração e aos contadores, nunca a dados de usuário final: `users/`, `sessions/`, `sign-ins/`, `overview/`, organizações de clientes, funções, importações, sessões de agente e e-mails de teste ainda exigem uma sessão no console.

A configuração `agent_humans_only` se aplica à aplicação inteira. Somente um proprietário ou administrador da organização pode alterá-la. Uma chave nomeada recebe `403 owner_or_admin_required`. Ativar a configuração também exige uma passkey cadastrada (`passkey_required`).

## Erros

| Resposta | Significado |
| - | - |
| `401` | Nenhuma credencial. |
| `403` | Uma credencial que não pode configurar esta aplicação, ou um dos próprios limites dela: `ip_not_allowed`, uma chave expirada, uma chave somente leitura em uma rota de escrita. |
| `409 {"detail": "product_disabled"}` | A autenticação está desativada para a aplicação, então uma alteração de configuração feita com um grant ou uma chave é recusada. Uma pessoa a ativa no console. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | O recurso solicitado não foi encontrado. |


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