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

# Autenticação da API: requisições seguras à API de KYC

> Autentique requisições à API da Didit com uma chave com escopo no cabeçalho x-api-key. Chave errada ou expirada retorna 401; sem chave, 403.



Prompt de autenticação da API
        Copiar o prompt para a área de transferência



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

Colar em

## Como encontrar sua chave de APINa Didit, as chaves de API são vinculadas a uma **Aplicação** específica da sua conta. Uma Aplicação é um espaço de trabalho onde você configura fluxos de verificação (workflows) e gerencia verificações de um projeto ou ambiente específico.Toda Aplicação recebe, ao ser criada, uma chave de API primária com acesso total. Você pode adicionar outras chaves além dela, cada uma apenas com o acesso de que um serviço ou parceiro precisa. Para encontrar suas chaves:**1. Faça login no Business Console**Acesse o [**Didit Business Console**](https://business.didit.me) e entre na sua conta.**2. Selecione sua Aplicação**Escolha a **Aplicação** com a qual deseja trabalhar no menu suspenso na parte superior.**3. Abra as chaves de API**Navegue até **Developers -> API keys** na barra lateral esquerda.**4. Copie ou crie uma chave**A chave **Primária** é o segredo próprio da Aplicação. Crie uma nova chave para dar a um serviço ou parceiro o seu próprio segredo, com o acesso de que ele precisa.> [!WARNING]
>
> **Sua chave de API é um segredo — trate-a como uma senha.**
>
> A chave primária concede acesso total à API em nome da sua Aplicação. Nunca a exponha em código de frontend, repositórios públicos ou bundles do lado do cliente. Mantenha-a exclusivamente no servidor.### Formato da chave de APIAs novas chaves de API começam com `sk_live_` para uma aplicação de produção ou `sk_test_` para uma aplicação de sandbox, seguidas de 43 caracteres seguros para URL (letras, dígitos, `-` e `_`).
As chaves criadas antes deste formato não têm prefixo e continuam funcionando sem alterações.
Envie a chave inteira, incluindo o prefixo, no cabeçalho `x-api-key`, e não rejeite uma chave por ela não ter prefixo.## Como encontrar o ID da sua organizaçãoO **ID da organização** é o UUID que identifica sua organização. Você o usa em caminhos de API no escopo da organização, como `/auth/v2/organizations/me/{org_id}/applications/`. Você pode copiá-lo diretamente do Business Console, sem precisar de nenhuma chamada à API:**1. Abra as configurações da organização**No [**Didit Business Console**](https://business.didit.me), acesse **Configurações da organização**.**2. Copie o ID da organização**O campo **ID da organização** mostra o UUID da sua organização ao lado do nome dela, com um botão para copiar para a área de transferência.***## Como fazer requisições autenticadasPara autenticar uma requisição à API, inclua sua chave de API secreta no cabeçalho HTTP `x-api-key`.Veja um exemplo de requisição autenticada ao endpoint `Create Session`:```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## Tratamento de errosSe sua chave de API estiver errada, malformada ou revogada, a API retorna `401 Unauthorized`:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Uma chave expirada também retorna `401`, com `"detail": "This API key has expired."`.
Uma requisição sem chave retorna `403` com `"detail": "You do not have permission to perform this action."`.| Código de status | Significado |
| - | - |
| **401** | A chave de API está errada, malformada, revogada ou expirada |
| **403** | Nenhuma chave de API foi enviada, a chave não tem acesso ao recurso ou à ação solicitada, ou a requisição veio de um endereço fora da lista de IPs da chave |
| **403** com `"code": "application_deleted"` | A chave pertence a uma aplicação que foi excluída. A API retorna essa resposta por alguns minutos após a exclusão e, depois, recusa a chave como qualquer chave inválida. Não tente novamente: a aplicação e suas chaves não existem mais. |
| **404** | Em uma rota de sessão: a sessão não pertence aos fluxos de trabalho nem aos status da chave |A página [Erros da API](https://docs.didit.me/pt-br/integration/api-errors.md) lista todos os status, corpos de resposta e códigos.***## Chaves de API com escopoDê a cada serviço ou parceiro sua própria chave em vez de compartilhar a primária.
Cada chave tem seu próprio nível de acesso: nenhum, de leitura ou de escrita para cada recurso (sessões, decisões, mídia, pessoas, empresas, transações, fluxos, webhooks, configurações da aplicação, análises), além de limites opcionais para alguns fluxos, somente para sessões aprovadas, uma lista de endereços IP e uma data de validade.
Você pode rotacionar uma chave com um período de sobreposição de 24 horas e revogá-la imediatamente.As chaves criadas antes da existência do acesso com escopo mantêm acesso total.Consulte [Chaves de API](https://docs.didit.me/pt-br/console/api-keys.md) para ver as predefinições, os recursos que cada uma abrange e como a API responde a uma chave com escopo.> [!TIP]
>
> Se você receber um erro `401`, verifique se está usando a chave de API correta para a Aplicação certa e se ela não foi regenerada.


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