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

# Registo programático: API de KYC para agentes de IA

> Registe-se e obtenha credenciais da API Didit em 2 chamadas, sem browser. Verificação de identidade para agentes de IA: Cursor, Claude, Devin.

## Visão geral

O Didit é a **plataforma de verificação de identidade mais preparada para agentes**. Os agentes de programação com IA (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) podem registar-se, configurar fluxos e começar a verificar identidades, tudo de forma programática, sem nunca abrirem um navegador.

**Porque é que os agentes gostam do Didit:**

* **2 chamadas à API** desde o zero até às credenciais (registo + verify-email).
* **Não é necessário navegador**: totalmente sem interface, ideal para CI/CD e fluxos de agentes.
* **Sem segundo fator numa conta de API nova:** os tokens são devolvidos de imediato após a verificação do e-mail.
* **Organização e aplicação provisionadas automaticamente**, com `api_key` na resposta da verificação.
* **API de gestão completa**: configure fluxos de verificação, questionários, listas e faturação, tudo através da API.
* **Servidor MCP disponível**: os agentes podem descobrir e usar as ferramentas do Didit de forma nativa.

O contrato completo está publicado em [openapi-auth.json](https://docs.didit.me/openapi-auth.json); os endpoints abaixo foram auditados com base nesse contrato.

## URL base

Todos os endpoints deste guia estão no **host de autenticação**:

```
https://apx.didit.me/auth/v2
```

Este é um host diferente da API de verificação (`https://verification.didit.me/v3`). O host de autenticação emite tokens de acesso JWT e gere as aplicações. O host de verificação executa sessões, AML, fluxos e outras funcionalidades, autenticado com a `api_key` de longa duração que obtém através deste processo.

## Início rápido

> [!WARNING]
>
> **Utilize um endereço de e-mail real e capaz de receber mensagens.** O endpoint envia o código de verificação de forma síncrona, por isso os domínios de teste reservados (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) são rejeitados pelo serviço de envio de e-mail e a chamada devolve um `500`. Substitua o marcador `you@yourdomain.com` abaixo por uma caixa de correio que consiga ler.

### Passo 1: Registar

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**Resposta** (`201 Created`):

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

Um código de verificação alfanumérico de 6 caracteres (por exemplo, `A3K9F2`) é enviado por e-mail para o endereço. **O código expira 10 minutos após o envio.** Se expirar, chame novamente este endpoint com o mesmo e-mail e a mesma palavra-passe: para uma conta ainda não verificada, devolve `200` com `"A new verification code has been sent to your email."` e um código novo. Um endpoint dedicado, `POST /programmatic/resend-otp/` (corpo: `{"email", "password"}`), também volta a enviar o código, com um intervalo de 60 segundos entre envios. Ambas as rotas partilham o limite de pedidos de registo indicado abaixo.

### Passo 2: Verificar o código e obter as credenciais

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
```

**Resposta** (`200 OK`):

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

Já tem tudo o que precisa. Guarde `application.api_key` de forma segura e envie-a no cabeçalho `x-api-key` em cada chamada à API de verificação.

> [!NOTE]
>
> Os tokens são **JWT assinados com RS256**. `expires_in` tem por defeito **86400 segundos (24 horas)**. O token de acesso só é necessário para os endpoints de gestão em `apx.didit.me/auth/v2`. O tráfego da API de verificação em `verification.didit.me/v3` é autenticado com a `api_key` de longa duração, e não com o JWT.

### Passo 3: Utilizar a API

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Inícios de sessão seguintes

A partir de qualquer máquina que utilize no futuro, troque o seu e-mail e a sua palavra-passe por um JWT novo:

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

Devolve `access_token` + `refresh_token` diretamente, sem navegador. A partir daí, chame `GET /organizations/me/` para descobrir o seu `org_id` (o `uuid` da organização). Depois, chame `GET /organizations/me/{org_id}/applications/` para listar as aplicações da organização (o `uuid` de cada entrada é um `app_id`) e, por fim, `GET /organizations/me/{org_id}/applications/{app_id}/` para recuperar a `api_key`.

> [!NOTE]
>
> As contas criadas na consola com e-mail e palavra-passe também podem usar `POST /programmatic/login/` depois de o e-mail ser verificado. As contas da consola que só usam OAuth têm de definir uma palavra-passe antes de utilizarem este endpoint de início de sessão sem interface.

### Quando o início de sessão pede mais

`POST /programmatic/login/` só devolve tokens quando a conta não tem um segundo fator.
Existem outras três respostas possíveis, e um agente que faça scripts de início de sessão deve tratá-las:

| Conta | Resposta |
| - | - |
| Tem uma aplicação de autenticação ou uma chave de acesso (passkey) | `200` com `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` e sem tokens |
| A organização impõe SSO | `403` com `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| Foi recuperada e ainda não tem um método de início de sessão | `403` com `"code": "recovery_setup_required"`, e uma ligação para configurar um método é enviada para o endereço da conta |

Uma chave de API não precisa de início de sessão, por isso utilize uma para tudo o que seja automatizado: uma conta com segundo fator não consegue concluir o início de sessão através deste endpoint.

## Requisitos da palavra-passe

Aplicados no servidor, **uma regra de cada vez**: a primeira falha interrompe a validação e devolve um erro em array simples, como `["Password must contain at least one uppercase letter."]`. (Outros erros de validação neste endpoint usam o envelope `{"password": [...]}`, indexado pelo campo. O formato em array simples nas regras de força da palavra-passe é uma inconsistência conhecida do servidor; no código do cliente, trate-o como `{"password": [...]}`.)

| Regra | Detalhe |
| - | - |
| Comprimento mínimo | 8 caracteres |
| Letra maiúscula | Pelo menos uma `A–Z` |
| Letra minúscula | Pelo menos uma `a–z` |
| Dígito | Pelo menos um `0–9` |
| Carácter especial | Pelo menos um destes: `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## Limites de pedidos e bloqueios

Três controlos independentes protegem o host de autenticação. Qualquer um deles pode disparar uma resposta `429`; o cabeçalho de resposta `Retry-After` indica quanto tempo deve esperar antes de voltar a tentar.

| Superfície | Limite |
| - | - |
| Registo | **5** tentativas por **IP** por **hora** (partilhadas com `POST /programmatic/resend-otp/`). |
| Verificação de e-mail | **10** tentativas de código por **e-mail** por **hora** e **50** por **IP** de origem por **hora**, além de uma espera exponencial entre tentativas (30 s, duplicando a cada falha, com o máximo de 1 hora). |
| Início de sessão (IP) | **20** tentativas por **IP** por **minuto**, e **100** por **IP** por **hora**. |
| Início de sessão (e-mail) | Bloqueio progressivo da conta: **5** falhas consecutivas → bloqueio de 15 min; **10** → 1 hora; **20** → 24 horas. |

O corpo de uma resposta `429` tem este aspeto:

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

Os limites de pedidos da API de verificação (por exemplo, 600 sessões/min) são independentes e estão documentados em [Limitação de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md).

## Gerir aplicações

Depois de autenticado, pode obter, criar ou atualizar aplicações dentro da sua organização.

Esta funcionalidade é ideal para **revendedores** que pretendem uma aplicação por cliente. Cada aplicação tem o seu próprio `client_id`, `api_key`, metadados e definições. Também é útil quando a sua organização tem produtos, marcas, regiões, ambientes ou casos de utilização diferentes que pretende manter separados.

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

Listar, criar ou atualizar aplicações exige que o utilizador seja **proprietário** ou **administrador** da organização de destino; caso contrário, a resposta é `403`.

## O que podem os agentes fazer após o registo?

Com o `api_key`, os agentes têm acesso total à API de verificação. Endpoints auditados em `https://verification.didit.me/v3`:

| API | O que faz |
| - | - |
| `POST /v3/session/` | Criar uma sessão de verificação. |
| `GET /v3/sessions/` | Listar sessões. |
| `GET /v3/session/{id}/decision/` | Obter a decisão V3 (matrizes no plural — ver Modelos de dados). |
| `GET /v3/workflows/` | Listar fluxos de verificação. |
| `GET /v3/questionnaires/` | Listar questionários personalizados. |
| `GET /v3/users/` | Listar utilizadores finais (indexados por `vendor_data`). |
| `GET /v3/billing/balance/` | Consultar o saldo de créditos. |
| `POST /v3/billing/top-up/` | Carregar saldo de créditos. |
| `GET /v3/webhook/destinations/` | Gerir destinos de webhook (listar / criar / atualizar / eliminar). |

Consulte a [referência da API de Gestão](https://docs.didit.me/pt/sessions-api/management-api.md) para ver a superfície completa.

## Integração com o servidor MCP

Para a melhor experiência com agentes, use o servidor MCP da Didit alojado em `https://mcp.didit.me/mcp`. Não precisa de chave de API: na primeira ligação, o seu cliente abre um navegador, você **inicia sessão com a Didit** (OAuth 2.1 com PKCE) e o servidor age em seu nome, com as permissões da sua função na consola. Os clientes com suporte nativo a MCP remoto (Cursor, VS Code) usam esta entrada; o Claude na web e o Desktop adicionam-na como conector personalizado:

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}
```

Claude Code: `claude mcp add --transport http didit https://mcp.didit.me/mcp`. Os clientes que só suportam stdio (Windsurf, Zed) passam pela ponte `mcp-remote`, que executa o fluxo OAuth por si.

A chave de API que recebe através do fluxo de registo acima destina-se a chamar a API REST a partir do seu próprio backend; o MCP nunca a utiliza. Consulte a [visão geral do MCP](https://docs.didit.me/pt/integration/mcp/overview.md) e a [instalação por cliente](https://docs.didit.me/pt/integration/mcp/installation.md) para mais detalhes.

## Referência do envelope de erros

Todos os endpoints `apx.didit.me/auth/v2` partilham as mesmas três formas de resposta (ver `openapi-auth.json`):

* **Validação ao nível do campo**: `{"field": ["message", ...]}` com HTTP `400`.
* **Validação ao nível do formulário** (sobretudo na força da palavra-passe e nos erros de código de verificação): matriz simples `["Invalid or expired verification code."]` com HTTP `400`.
* **Autenticação / regra de negócio**: `{"detail": "..."}` com `400`, `401`, `403`, `404` ou `429`. As respostas `429` incluem o cabeçalho de resposta `Retry-After`, que indica quanto tempo deve esperar antes de voltar a tentar (o corpo tem apenas `detail`).

O host de verificação devolve erros como `{"detail": "..."}` e as respostas 429 incluem `X-RateLimit-*` e `Retry-After`. Consulte [Limitação de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md).


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