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_keyna 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.
URL base
Todos os endpoints deste guia estão no host de autenticaçã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
Passo 1: Registar
201 Created):
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
200 OK):
application.api_key de forma segura e envie-a no cabeçalho x-api-key em cada chamada à API de verificação.
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
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: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.
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:
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": [...]}.)
Limites de pedidos e bloqueios
Três controlos independentes protegem o host de autenticação. Qualquer um deles pode disparar uma resposta429; o cabeçalho de resposta Retry-After indica quanto tempo deve esperar antes de voltar a tentar.
O corpo de uma resposta
429 tem este aspeto:
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óprioclient_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.
403.
O que podem os agentes fazer após o registo?
Com oapi_key, os agentes têm acesso total à API de verificação. Endpoints auditados em https://verification.didit.me/v3:
Consulte a referência da API de Gestão 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 emhttps://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:
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 e a instalação por cliente para mais detalhes.
Referência do envelope de erros
Todos os endpointsapx.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 HTTP400. - 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 HTTP400. - Autenticação / regra de negócio:
{"detail": "..."}com400,401,403,404ou429. As respostas429incluem o cabeçalho de respostaRetry-After, que indica quanto tempo deve esperar antes de voltar a tentar (o corpo tem apenasdetail).
{"detail": "..."} e as respostas 429 incluem X-RateLimit-* e Retry-After. Consulte Limitação de pedidos.