> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Registre programàtic: API de KYC per a agents d'IA

> Obtén les credencials de l'API de Didit en 2 crides, sense navegador. La plataforma de KYC més nativa per a agents: Cursor, Claude, Devin.

## 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](https://docs.didit.me/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ó**:

```
https://apx.didit.me/auth/v2
```

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

> [!WARNING]
>
> **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

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**Resposta** (`201 Created`):

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

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

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
```

**Resposta** (`200 OK`):

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

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ó.

> [!NOTE]
>
> 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

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Inicis de sessió posteriors

Des de qualsevol equip, en el futur, intercanvia el teu correu electrònic i la contrasenya per un JWT nou:

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

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`.

> [!NOTE]
>
> 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:

| Compte | Resposta |
| - | - |
| Té una aplicació d'autenticació o una clau d'accés (passkey) | `200` amb `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` i sense tokens |
| La seva organització imposa SSO | `403` amb `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| S'ha recuperat i encara no té cap mètode d'inici de sessió | `403` amb `"code": "recovery_setup_required"`, i un enllaç per configurar-ne un s'envia a l'adreça del compte |

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": [...]}`.)

| Regla | Detall |
| - | - |
| Longitud mínima | 8 caràcters |
| Lletra majúscula | Almenys una `A–Z` |
| Lletra minúscula | Almenys una `a–z` |
| Dígit | Almenys un `0–9` |
| Caràcter especial | Almenys un dels següents: `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## 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.

| Superfície | Límit |
| - | - |
| Registre | **5** intents per **IP** per **hora** (compartits amb `POST /programmatic/resend-otp/`). |
| Verificació de correu | **10** intents de codi per **correu** per **hora** i **50** per IP d'origen per **hora**, a més d'una espera exponencial entre intents (30 s, que es duplica a cada error, amb un màxim d'1 hora). |
| Inici de sessió (IP) | **20** intents per **IP** per **minut**, i **100** per **IP** per **hora**. |
| Inici de sessió (correu) | Bloqueig progressiu del compte: **5** errors consecutius → bloqueig de 15 min; **10** → 1 hora; **20** → 24 hores. |

El cos d'una resposta `429` té aquest aspecte:

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

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](https://docs.didit.me/ca/integration/rate-limiting.md).

## 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.

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

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`:

| API | Què fa |
| - | - |
| `POST /v3/session/` | Crea una sessió de verificació. |
| `GET /v3/sessions/` | Llista les sessions. |
| `GET /v3/session/{id}/decision/` | Obté la decisió V3 (matrius en plural; consulta Models de dades). |
| `GET /v3/workflows/` | Llista els fluxos de treball de verificació. |
| `GET /v3/questionnaires/` | Llista els qüestionaris personalitzats. |
| `GET /v3/users/` | Llista els usuaris finals (indexats per `vendor_data`). |
| `GET /v3/billing/balance/` | Consulta el saldo de crèdits. |
| `POST /v3/billing/top-up/` | Recarrega crèdits. |
| `GET /v3/webhook/destinations/` | Gestiona les destinacions de webhook (llistar / crear / actualitzar / eliminar). |

Consulta la [Referència de l'API de gestió](https://docs.didit.me/ca/sessions-api/management-api.md) 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:

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}
```

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](https://docs.didit.me/ca/integration/mcp/overview.md) i la [instal·lació per client](https://docs.didit.me/ca/integration/mcp/installation.md) 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](https://docs.didit.me/ca/integration/rate-limiting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.