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_keyna 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.
URL base
Todos os endpoints deste guia ficam no host de autenticaçã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
Etapa 1: Registro
201 Created):
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
200 OK):
application.api_key com segurança e envie-a como o cabeçalho x-api-key em todas as chamadas à API de verificação.
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
Logins posteriores
Em qualquer máquina que você usar no futuro, troque seu e-mail e sua senha por um novo JWT: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.
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:
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.)
Limites de requisições e bloqueios
Três controles independentes protegem o host de autenticação. Qualquer um deles pode gerar uma resposta429, e o cabeçalho de resposta Retry-After informa quanto tempo você deve esperar antes de tentar novamente.
O corpo de uma resposta
429 tem este formato:
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ópriosclient_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.
403.
O que os agentes podem fazer após o cadastro
Com aapi_key, os agentes têm acesso total à API de verificação. Rotas auditadas em https://verification.didit.me/v3:
Consulte a referência da Management API 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 emhttps://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:
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 e a instalação por cliente para mais detalhes.
Referência do envelope de erro
Todos os endpoints deapx.didit.me/auth/v2 compartilham os mesmos três formatos de resposta (consulte openapi-auth.json):
- Validação por campo:
{"field": ["message", ...]}com HTTP400. - 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 HTTP400. - Autenticação / regra de negócio:
{"detail": "..."}com400,401,403,404ou429. As respostas429trazem um cabeçalho de respostaRetry-Afterque informa quanto tempo esperar antes de tentar novamente (o corpo contém apenasdetail).
{"detail": "..."}, e as respostas 429 incluem X-RateLimit-* e Retry-After. Consulte Limites de requisições.