Saltar para o conteúdo principal

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_key na 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.
O contrato completo está publicado em openapi-auth.json; os endpoints abaixo foram auditados com base nesse contrato.

URL base

Todos os endpoints deste guia estão no host de autenticação:
Este é um host diferente da API de verificaçã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

Utilize um endereço de e-mail real e capaz de receber mensagens. O endpoint envia o código de verificação de forma síncrona, por isso os domínios de teste reservados (@example.com, @example.org, @*.test, @*.example, @*.invalid) são rejeitados pelo serviço de envio de e-mail e a chamada devolve um 500. Substitua o marcador you@yourdomain.com abaixo por uma caixa de correio que consiga ler.

Passo 1: Registar

Resposta (201 Created):
Um código de verificação alfanumérico de 6 caracteres (por exemplo, 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

Resposta (200 OK):
Já tem tudo o que precisa. Guarde 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:
Devolve 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 resposta 429; 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:
Os limites de pedidos da API de verificação (por exemplo, 600 sessões/min) são independentes e estão documentados em Limitação de pedidos.

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óprio client_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.
Listar, criar ou atualizar aplicações exige que o utilizador seja proprietário ou administrador da organização de destino; caso contrário, a resposta é 403.

O que podem os agentes fazer após o registo?

Com o api_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 em https://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 Code: 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 endpoints apx.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 HTTP 400.
  • 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 HTTP 400.
  • Autenticação / regra de negócio: {"detail": "..."} com 400, 401, 403, 404 ou 429. As respostas 429 incluem o cabeçalho de resposta Retry-After, que indica quanto tempo deve esperar antes de voltar a tentar (o corpo tem apenas detail).
O host de verificação devolve erros como {"detail": "..."} e as respostas 429 incluem X-RateLimit-* e Retry-After. Consulte Limitação de pedidos.
Última modificação em 7 de novembro de 2026