Pular para o conteúdo principal

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; os endpoints abaixo são auditados em relação a ele.

URL base

Todos os endpoints deste guia ficam no host de autenticação:
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

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

Resposta (201 Created):
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

Resposta (200 OK):
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.
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:
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.
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 resposta 429, 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:
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.

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.
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: 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 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:
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 e a instalação por cliente 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.
Última modificação em 1 de novembro de 2026