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

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

> Cadastre-se e obtenha credenciais da API da Didit em 2 chamadas de API, sem navegador. KYC nativo para agentes de IA como Cursor, Claude e Devin.

## Visão geral

A Didit é a **plataforma de verificação de identidade mais amigável para agentes**. Agentes de programação com IA (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) conseguem se registrar, configurar fluxos de verificação (workflows) e começar a verificar identidades, tudo de forma programática, sem nunca abrir um navegador.

**Por que os agentes adoram a Didit:**

* **2 chamadas de API** para obter credenciais (registro + verificação de e-mail).
* **Nenhum navegador necessário**: totalmente headless, ideal para CI/CD e fluxos de agentes.
* **Sem segundo fator em uma nova conta de API:** os tokens são retornados imediatamente 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 gerenciamento completa**: configure fluxos, questionários, listas e faturamento, tudo via API.
* **Servidor MCP** disponível: os agentes podem descobrir e usar as ferramentas da Didit nativamente.

O contrato completo está publicado como [openapi-auth.json](https://docs.didit.me/openapi-auth.json); os endpoints abaixo são auditados em relação a ele.

## URL base

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

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

Esse host é diferente do da API de verificação (`https://verification.didit.me/v3`). O host de autenticação emite tokens de acesso JWT e gerencia aplicações. O host de verificação executa sessões, AML, fluxos etc., com autenticação feita pela `api_key` de longa duração que você obtém neste fluxo.

## Início rápido

> [!WARNING]
>
> **Use um endereço de e-mail real e que receba mensagens.** O endpoint envia o código de verificação de forma síncrona, então domínios de teste reservados (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) são rejeitados na entrega do e-mail e a chamada retorna `500`. Substitua o placeholder `you@yourdomain.com` abaixo por uma caixa de entrada que você consiga ler.

### Etapa 1: Registro

```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 para o endereço de e-mail. **O código expira 10 minutos após o envio**. Se ele expirar, chame este endpoint novamente com o mesmo e-mail e a mesma senha: para uma conta ainda não verificada, ele retorna `200` com `"A new verification code has been sent to your email."` e um novo código. Um endpoint dedicado `POST /programmatic/resend-otp/` (corpo: `{"email", "password"}`) também reenvia o código, com um intervalo de espera de 60 segundos entre envios; as duas rotas compartilham o limite de requisições de registro descrito abaixo.

### Etapa 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"
  }
}
```

Agora você tem tudo de que precisa. Armazene `application.api_key` com segurança e envie-a como o cabeçalho `x-api-key` em todas as chamadas à API de verificação.

> [!NOTE]
>
> Os tokens são **JWTs assinados com RS256**. `expires_in` tem como padrão **86400 segundos (24 horas)**. O token de acesso só é necessário para os endpoints de gerenciamento 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, não com o JWT.

### Etapa 3: Usar a API

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

## Logins posteriores

Em qualquer máquina que você usar no futuro, troque seu e-mail e sua senha por um novo JWT:

```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"}'
```

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

> [!NOTE]
>
> Contas de e-mail/senha criadas no console também podem usar `POST /programmatic/login/` depois que o e-mail for verificado. Contas do console que usam apenas OAuth precisam definir uma senha antes de usar este endpoint de login headless.

### Quando o login pede mais

`POST /programmatic/login/` retorna tokens apenas quando a conta não tem segundo fator.
Há outras três respostas possíveis, e um agente que automatiza o login deve tratá-las:

| Conta | Resposta |
| - | - |
| Tem um app autenticador ou uma passkey | `200` com `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` e nenhum token |
| A organização exige SSO | `403` com `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| Foi recuperada e ainda não tem método de login | `403` com `"code": "recovery_setup_required"`, e um link para configurar um método é enviado ao endereço da conta |

Uma chave de API não exige login, então use uma para qualquer automação: uma conta com segundo fator não consegue concluir o login por este endpoint.

## Requisitos de senha

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

| 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` |
| Caractere especial | Pelo menos um de `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## Limites de requisições e bloqueios

Três controles independentes protegem o host de autenticação. Qualquer um deles pode gerar uma resposta `429`, e o cabeçalho de resposta `Retry-After` informa quanto tempo você deve esperar antes de tentar novamente.

| Fluxo | Limite |
| - | - |
| Cadastro | **5** tentativas por **IP** por **hora** (compartilhado 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 backoff exponencial entre as tentativas (30 s, dobrando a cada falha, com teto de 1 hora). |
| Login (IP) | **20** tentativas por **IP** por **minuto** e **100** por **IP** por **hora**. |
| Login (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 formato:

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

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

## Gerenciamento de aplicações

Depois de se autenticar, você pode consultar, criar ou atualizar aplicações dentro da sua organização.

Isso é ideal para **revendedores** que querem uma aplicação por cliente. Cada aplicação tem seus próprios `client_id`, `api_key`, metadados e configurações. Também é útil quando sua organização tem produtos, marcas, regiões, ambientes ou casos de uso diferentes que você quer 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"
  }'
```

Para listar, criar ou atualizar aplicações, o usuário precisa ser **proprietário** ou **administrador** da organização de destino; caso contrário, a resposta é `403`.

## O que os agentes podem fazer após o cadastro

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

| API | O que faz |
| - | - |
| `POST /v3/session/` | Cria uma sessão de verificação. |
| `GET /v3/sessions/` | Lista as sessões. |
| `GET /v3/session/{id}/decision/` | Obtém a decisão V3 (arrays no plural; consulte Modelos de dados). |
| `GET /v3/workflows/` | Lista os fluxos de verificação (workflows). |
| `GET /v3/questionnaires/` | Lista os questionários personalizados. |
| `GET /v3/users/` | Lista os usuários finais (indexados por `vendor_data`). |
| `GET /v3/billing/balance/` | Consulta o saldo de créditos. |
| `POST /v3/billing/top-up/` | Recarrega créditos. |
| `GET /v3/webhook/destinations/` | Gerencia os destinos de webhook (listar / criar / atualizar / excluir). |

Consulte a [referência da Management API](https://docs.didit.me/pt-br/sessions-api/management-api.md) para ver todos os endpoints disponíveis.

## Integração com o servidor MCP

Para a melhor experiência com agentes, use o servidor MCP hospedado da Didit em `https://mcp.didit.me/mcp`. Ele não precisa de chave de API: na primeira conexão, seu cliente abre um navegador, você usa **Entrar com a Didit** (OAuth 2.1 com PKCE) e o servidor passa a agir em seu nome, com as permissões da sua função no console. Clientes com suporte nativo a MCP remoto (Cursor, VS Code) usam esta entrada; o Claude na web e o Claude Desktop o adicionam 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`. Clientes que só suportam stdio (Windsurf, Zed) passam pela ponte `mcp-remote`, que executa o fluxo OAuth para você.

A chave de API que você recebe no fluxo de cadastro acima serve para 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-br/integration/mcp/overview.md) e a [instalação por cliente](https://docs.didit.me/pt-br/integration/mcp/installation.md) para mais detalhes.

## Referência do envelope de erro

Todos os endpoints de `apx.didit.me/auth/v2` compartilham os mesmos três formatos de resposta (consulte `openapi-auth.json`):

* **Validação por campo**: `{"field": ["message", ...]}` com HTTP `400`.
* **Validação do formulário** (em especial erros de força da senha e de código de verificação): array 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` trazem um cabeçalho de resposta `Retry-After` que informa quanto tempo esperar antes de tentar novamente (o corpo contém apenas `detail`).

O host de verificação retorna erros no formato `{"detail": "..."}`, e as respostas 429 incluem `X-RateLimit-*` e `Retry-After`. Consulte [Limites de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md).


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