> ## 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 por API

> Configure a Didit por API: ative métodos de início de sessão, marca, definições e proteção com autorização aprovada ou chave de API.

O Didit Authentication permite-lhe ativar métodos de início de sessão e consultar as definições da sua aplicação através de API. Utilize uma concessão aprovada pelo proprietário ou uma chave de API com nome e com o âmbito `authentication`.

> [!WARNING]
>
> A Autenticação é uma funcionalidade nova. Configure primeiro um método numa aplicação de sandbox e, depois, na sua aplicação de produção.

Todos os pedidos abaixo são enviados para a 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 estão descritas em `openapi-authentication.json`, na etiqueta `Setup`, a partir do qual os SDK de servidor são regenerados.

## Qual credencial usar

Qualquer uma das três credenciais funciona, e cada uma está limitada ao que o seu titular aprovou.

| Credencial | Enviada como | O que pode fazer |
| - | - | - |
| Chave de API nomeada com o âmbito `authentication` | `x-api-key: <key>` | Configura a sua própria aplicação e pode lê-la. 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 da consola | `Authorization: Bearer <console session token>` | Lê ou altera definições de acordo com o vínculo da pessoa à organização e com a sua função. As vistas do utilizador final também exigem uma sessão da consola e as permissões adequadas. |

Estas credenciais são recusadas com `403` em todos os endpoints de configuração, independentemente do que o pedido solicita:

* O **segredo principal** da aplicação.
* Um token obtido em `POST /programmatic/login`, que é emitido para a aplicação e não para a consola.
* Uma chave **sem** o âmbito `authentication`, incluindo uma chave criada com todos os recursos no nível mais alto: esses aparecem listados como acesso total, mantêm `scopes` vazio e não são aceites nestes endpoints.
* Uma chave de **outra aplicação**, uma concessão limitada a `didit:verification` e uma concessão aprovada para outra organização.

Um pedido sem qualquer credencial recebe `401`. Além disso, uma concessão ou uma chave mantém os seus próprios limites: a concessão mantém os seus âmbitos, organizações e a função da pessoa; a chave mantém os seus âmbitos, a lista de IP permitidos e a validade.

## Aprovar acesso

### Com uma chave de API com nome

Abra **Developers -> API keys** na [Business Console](https://business.didit.me) e crie uma chave para a aplicação que está a configurar. Atribua-lhe o recurso `authentication` com permissão de **leitura** ou de **escrita**: a leitura cobre todas as chamadas que leem a configuração (`GET`); a escrita cobre todas as chamadas que a alteram (`POST`, `PUT`, `PATCH`, `DELETE`) e também a leem. Consulte [Chaves de API](https://docs.didit.me/pt/console/api-keys.md) para a validade, as listas de permissão de IP e a rotação; uma chave pertence a uma só aplicação e funciona apenas para essa aplicação.

### Através de uma ligação MCP

Um agente ligado ao servidor MCP da Didit usa a autorização que o respetivo proprietário aprovou no ecrã de consentimento, com `didit:management`. Consulte [Autenticação MCP](https://docs.didit.me/pt/integration/mcp/authentication.md#iniciar-sessão-com-a-didit).

### Para um proprietário sem palavra-passe

A autorização por código de dispositivo ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) permite que um proprietário que inicie sessão com o Google, uma chave de acesso ou um código enviado por e-mail aprove o mesmo acesso a partir de qualquer navegador, sem introduzir uma palavra-passe. Consulte [iniciar sessão sem navegador](https://docs.didit.me/pt/integration/mcp/authentication.md#iniciar-sessão-sem-navegador-código-de-dispositivo).

## Ativar o código por e-mail

Quando o método não requer credenciais, `PUT methods/{name}/` aceita `enabled` e nada mais.

```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 devolve o método tal como se encontra atualmente:

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

Ao ler a configuração, a entrada do código por e-mail inclui `credential_source: null`. Os métodos que estão sempre ativos não podem ser desativados: esse pedido responde `{"enabled": "always_on"}`.

## Ativar o Google

Um método social exige as credenciais da sua própria aplicação OAuth ou da aplicação de teste da Didit numa aplicação sandbox.

### Com a sua própria aplicação 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-..."}}'
```

Registe o `callback_uri` devolvido na resposta no seu fornecedor. O segredo é só de escrita: nenhuma resposta o devolve, e o `client_id` é a única parte que pode ser lida novamente. Ativar um método sem credenciais, quando não existiam credenciais guardadas antes, responde com `{"credentials": "required"}`.

### Com a aplicação de teste da Didit (`didit_test`)

Uma **aplicação sandbox** pode usar as aplicações sociais da própria Didit em vez das suas, o que basta para concluir a configuração e comprovar que 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"}'
```

O `didit_test` abrange **Google, Microsoft, Apple e GitHub**, apenas em aplicações sandbox:

| Resposta | Quando |
| - | - |
| `{"credential_source": "sandbox_only"}` | A aplicação está em produção. As aplicações de teste nunca servem inícios de sessão em produção. |
| `{"credential_source": "unavailable"}` | A implementação não tem aplicação de teste para esse fornecedor, pelo que o método permanece desativado. |
| `200` com `configured: true` | A aplicação de teste serve o método, e a página de início de sessão alojada oferece-o. |

O `GET` à configuração indica em `didit_test_credentials` os fornecedores que uma aplicação de teste pode servir para esta aplicação. O valor é `false` para os quatro numa aplicação de produção.

## Ler a configuração

`GET` em `MANAGEMENT_BASE` serve para ler a configuração: todos os métodos, com `enabled` e `credential_source`, bem como os URLs de retorno, as regras de sessão e a política de registo.

```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, pelo que um único `GET` indica 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 à configuração feita com uma concessão de gestão ou uma chave de API nomeada devolve então `409` com `{"detail": "product_disabled"}`, e nada é gravado. Nenhuma chamada de configuração ativa a Autenticação: é uma pessoa que a ativa para a aplicação na consola, e as 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 predefinida de membro, eventos de webhook desativados |
| `onboarding/` | `GET`, `PATCH` | Os passos de configuração concluídos e se as pessoas iniciam sessão na página alojada ou nos seus próprios ecrãs |
| `branding/` | `GET`, `PATCH` | Os textos das páginas alojadas e as ligações legais (o logótipo e as cores vêm da Personalização) |
| `protection/` | `GET`, `PATCH` | As políticas de proteção contra bots ([proteção contra bots](https://docs.didit.me/pt/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | O nível de verificação no registo, as regras de autenticação reforçada e as declarações do token |
| `emails/`, `emails/{key}/` | `GET` | Os e-mails de início de sessão que esta aplicação envia, e uma pré-visualização renderizada |
| `domain/` | `GET`, `PUT`, `DELETE` | A origem alojada e o domínio personalizado de início de sessão |
| `domain/verify/`, `domain/activate/` | `POST` | Verificar o DNS e o certificado do domínio e, em seguida, defini-lo como a origem canónica |
| `native-apps/` | `GET`, `PUT` | As apps iOS e Android que partilham as passkeys da aplicação |

Uma concessão ou uma chave tem acesso à configuração e aos respetivos contadores, nunca dados do utilizador final: `users/`, `sessions/`, `sign-ins/`, `overview/`, organizações de clientes, funções, importações, sessões de agentes e e-mails de teste continuam a exigir uma sessão na consola.

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

## Erros

| Resposta | Significado |
| - | - |
| `401` | Nenhuma credencial. |
| `403` | Uma credencial que não pode configurar esta aplicação, ou um dos seus próprios limites: `ip_not_allowed`, uma chave expirada, uma chave só de leitura num endpoint de escrita. |
| `409 {"detail": "product_disabled"}` | A autenticação está desativada para a aplicação, por isso uma alteração de configuração feita com uma concessão ou uma chave é recusada. Uma pessoa ativa-a na Business Console. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | O recurso pedido não foi encontrado. |


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