Saltar al contingut principal

Visió general

Didit és la plataforma de verificació d’identitat més amigable per als agents. Els agents de programació amb IA (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) poden registrar-se, configurar fluxos de treball i començar a verificar identitats, tot de manera programàtica i sense obrir mai un navegador. Per què els agents estimen Didit:
  • 2 crides a l’API des de zero fins a les credencials (register + verify-email).
  • No cal navegador: totalment sense interfície gràfica, ideal per a CI/CD i fluxos d’agents.
  • Sense segon factor en un compte d’API nou: els tokens es retornen immediatament després de verificar el correu electrònic.
  • Organització i aplicació aprovisionades automàticament, amb api_key a la resposta de verificació.
  • API de gestió completa: configura fluxos de treball, qüestionaris, llistes i facturació, tot via API.
  • Servidor MCP disponible: els agents poden descobrir i utilitzar les eines de Didit de manera nativa.
El contracte complet es publica com a openapi-auth.json; els endpoints següents s’han auditat amb aquest contracte.

URL base

Tots els endpoints d’aquesta guia es troben a l’host d’autenticació:
Aquest host és diferent de l’API de verificació (https://verification.didit.me/v3). L’host d’autenticació emet tokens d’accés JWT i gestiona les aplicacions. L’host de verificació executa les sessions, AML, els fluxos de treball, etc., i s’autentica amb la api_key de llarga durada que obtens amb aquest flux.

Inici ràpid

Utilitza una adreça de correu electrònic real i que pugui rebre missatges. L’endpoint envia el codi de verificació de manera síncrona, de manera que els dominis de prova reservats (@example.com, @example.org, @*.test, @*.example, @*.invalid) són rebutjats pel servei de lliurament de correu i la crida retorna un 500. Substitueix el marcador you@yourdomain.com que hi ha a continuació per una bústia que puguis llegir.

Pas 1: Registre

Resposta (201 Created):
Es envia per correu electrònic a l’adreça un codi de verificació de 6 caràcters alfanumèrics (p. ex. A3K9F2). El codi caduca 10 minuts després d’enviar-se: si caduca, torna a cridar aquest endpoint amb el mateix correu electrònic i la mateixa contrasenya. Per a un compte encara no verificat, retorna 200 amb "A new verification code has been sent to your email." i un codi nou. Un endpoint específic, POST /programmatic/resend-otp/ (cos: {"email", "password"}), també torna a enviar el codi, amb un temps d’espera de 60 segons entre enviaments. Les dues rutes comparteixen el límit de freqüència de registre que es descriu més avall.

Pas 2: Verifica el codi i obté les credencials

Resposta (200 OK):
Ja tens tot el que necessites. Desa application.api_key de manera segura i envia’l com a capçalera x-api-key en cada crida a l’API de verificació.
Els tokens són JWT signats amb RS256. expires_in té per defecte 86400 segons (24 hores). El token d’accés només cal per als endpoints de gestió a apx.didit.me/auth/v2; el trànsit de l’API de verificació a verification.didit.me/v3 s’autentica amb la api_key de llarga durada, no amb el JWT.

Pas 3: Utilitza l’API

Inicis de sessió posteriors

Des de qualsevol equip, en el futur, intercanvia el teu correu electrònic i la contrasenya per un JWT nou:
Retorna access_token + refresh_token directament, sense navegador. A partir d’aquí, fes una crida a GET /organizations/me/ per descobrir el teu org_id (el uuid de l’organització), després GET /organizations/me/{org_id}/applications/ per llistar les aplicacions de l’organització (el uuid de cada entrada és un app_id) i, finalment, GET /organizations/me/{org_id}/applications/{app_id}/ per recuperar la api_key.
Els comptes amb correu electrònic i contrasenya creats des de la consola també poden utilitzar POST /programmatic/login/ després de verificar el correu electrònic. Els comptes de consola que només usen OAuth han d’establir una contrasenya abans d’utilitzar aquest endpoint d’inici de sessió sense interfície.

Quan l’inici de sessió requereix passos addicionals

POST /programmatic/login/ només retorna tokens quan el compte no té cap segon factor. Hi ha tres altres respostes possibles, i un agent que escriu un script d’inici de sessió ha de gestionar-les: Una clau d’API no necessita inici de sessió, així que utilitza-la per a qualsevol tasca automatitzada: un compte amb un segon factor no pot completar l’inici de sessió a través d’aquest endpoint.

Requisits de la contrasenya

El servidor les aplica una regla cada vegada: el primer error talla la validació i retorna un array simple d’errors, com ara ["Password must contain at least one uppercase letter."]. (Els altres errors de validació d’aquest endpoint utilitzen l’embolcall {"password": [...]} indexat per camp. La forma d’array simple a les regles de força de la contrasenya és una inconsistència coneguda del servidor; en el codi del client, tracta-la com a {"password": [...]}.)

Límits de freqüència i bloquejos

Tres controls independents protegeixen l’host d’autenticació. Qualsevol d’ells pot provocar una resposta 429; la capçalera de resposta Retry-After indica quant de temps has d’esperar abans de tornar-ho a intentar. El cos d’una resposta 429 té aquest aspecte:
Els límits de freqüència de l’API de verificació (p. ex. 600 sessions/min) són independents i es documenten a Límit de freqüència.

Gestió d’aplicacions

Un cop autenticat, pots consultar, crear o actualitzar aplicacions dins de la teva organització. Això encaixa perfectament amb revenedors que volen una aplicació per client. Cada aplicació té el seu propi client_id, api_key, metadades i configuració. També és útil quan la teva organització té productes, marques, regions, entorns o casos d’ús diferents que vols mantenir separats.
Per consultar, crear o actualitzar aplicacions cal que l’usuari sigui propietari o administrador de l’organització de destinació; en cas contrari, la resposta és 403.

Què poden fer els agents després del registre?

Amb l’api_key, els agents tenen accés complet a l’API de verificació. Rutes auditades a https://verification.didit.me/v3: Consulta la Referència de l’API de gestió per a la superfície completa.

Integració amb el servidor MCP

Per a la millor experiència amb agents, fes servir el servidor MCP allotjat de Didit a https://mcp.didit.me/mcp. No necessita clau d’API: en connectar-te per primera vegada, el client obre un navegador, inicies sessió amb Didit (OAuth 2.1 amb PKCE) i el servidor actua en nom teu, amb els permisos del rol que tens a la consola. Els clients amb suport natiu de MCP remot (Cursor, VS Code) usen aquesta entrada; Claude web i Desktop l’afegeixen com a connector personalitzat:
Claude Code: claude mcp add --transport http didit https://mcp.didit.me/mcp. Els clients que només funcionen amb stdio (Windsurf, Zed) passen pel pont mcp-remote, que executa el flux OAuth per tu. La clau d’API que reps del flux de registre anterior serveix per cridar l’API REST des del teu propi backend; el MCP mai l’utilitza. Consulta la Visió general del MCP i la instal·lació per client per als detalls.

Referència del format d’errors

Tots els endpoints de apx.didit.me/auth/v2 comparteixen les mateixes tres formes de resposta (consulta openapi-auth.json):
  • Validació a nivell de camp: {"field": ["message", ...]} amb HTTP 400.
  • Validació a nivell de formulari (sobretot la fortalesa de la contrasenya i els errors del codi de verificació): array simple ["Invalid or expired verification code."] amb HTTP 400.
  • Autenticació / regla de negoci: {"detail": "..."} amb 400, 401, 403, 404 o 429. Les respostes 429 porten una capçalera de resposta Retry-After que indica quant de temps has d’esperar abans de tornar-ho a intentar (el cos només té detail).
L’host de verificació retorna els errors com a {"detail": "..."}, i les respostes 429 inclouen X-RateLimit-* i Retry-After; consulta Límit de freqüència.
Darrera modificació el 7 de novembre del 2026