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

# Autenticació de l'API: Sol·licituds segures a KYC

> Autentica les sol·licituds a l'API de Didit amb una clau a la capçalera x-api-key. Una clau errònia o caducada retorna 401; si falta, 403.



Prompt d'autenticació de l'API
        Copia el prompt al porta-retalls



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

Enganxa a

## Trobar la clau d'APIA Didit, les claus d'API tenen un àmbit definit a una **Aplicació** específica dins del teu compte. Una Aplicació és un espai de treball on pots configurar fluxos de treball i gestionar verificacions per a un projecte o entorn determinat.Cada Aplicació rep una clau d'API principal amb accés complet quan la crees. Pots afegir-hi més claus, cadascuna només amb l'accés que necessiti un servei o soci. Per trobar les teves claus:**1. Inicia sessió a la Business Console**Ves a la [**Didit Business Console**](https://business.didit.me) i inicia sessió.**2. Selecciona la teva Aplicació**Tria l'**Aplicació** amb la qual vols treballar al menú desplegable superior.**3. Obre les claus d'API**Navega a **Desenvolupadors -> Claus d'API** a la barra lateral esquerra.**4. Copia o crea una clau**La clau **Principal** és el secret propi de l'Aplicació. Crea una clau nova per donar a un servei o soci el seu propi secret, amb l'accés que necessiti.> [!WARNING]
>
> **La teva clau d'API és un secret; tracta-la com una contrasenya.**
>
> La clau principal proporciona accés complet a l'API en nom de la teva Aplicació. No l'exposis mai en codi de frontend, repositoris públics o paquets del costat del client. Mantén-la sempre exclusivament al costat del servidor.### Format de la clau d'APILes claus d'API noves comencen amb `sk_live_` per a una aplicació en producció o `sk_test_` per a una aplicació en sandbox, seguides de 43 caràcters segurs per a URL (lletres, dígits, `-` i `_`).
Les claus creades abans d'aquest format no tenen prefix i continuen funcionant sense canvis.
Envia la clau sencera, prefix inclòs, a la capçalera `x-api-key`, i no rebutgis cap clau pel fet de no tenir prefix.## Trobar el teu ID d'organitzacióEl teu **ID de l'organització** és l'UUID que identifica la teva organització. El fas servir en rutes d'API d'àmbit d'organització com ara `/auth/v2/organizations/me/{org_id}/applications/`. Pots copiar-lo directament des de la Business Console, sense necessitat de cap crida a l'API:**1. Obre la configuració de l'organització**A la [**Didit Business Console**](https://business.didit.me), ves a **Configuració de l'organització**.**2. Copia l'ID de l'organització**El camp **ID de l'organització** mostra l'UUID de la teva organització al costat del nom de l'organització, amb un botó per copiar al porta-retalls.***## Fer sol·licituds autenticadesPer autenticar una sol·licitud a l'API, inclou la teva clau d'API secreta a la capçalera HTTP `x-api-key`.A continuació tens un exemple d'una sol·licitud autenticada a l'endpoint `Create Session`:```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## Gestió d'errorsSi la teva clau d'API és incorrecta, està mal formada o s'ha revocat, l'API retorna `401 Unauthorized`:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Una clau caducada també retorna `401`, amb `"detail": "This API key has expired."`.
Una sol·licitud sense clau retorna `403` amb `"detail": "You do not have permission to perform this action."`.| Codi d'estat | Significat |
| - | - |
| **401** | La clau d'API és incorrecta, està mal formada, s'ha revocat o ha caducat |
| **403** | No s'ha enviat cap clau d'API, la clau no té accés al recurs o acció sol·licitats, o la sol·licitud prové d'una adreça que no figura a la llista d'IP de la clau |
| **403** amb `"code": "application_deleted"` | La clau pertany a una aplicació que s'ha eliminat. L'API respon això durant uns minuts després de l'eliminació i, després, rebutja la clau com qualsevol clau no vàlida. No reintentis: l'aplicació i les seves claus ja no existeixen. |
| **404** | En una ruta de sessió: la sessió queda fora dels fluxos de treball o estats de la clau |La pàgina d'[errors de l'API](https://docs.didit.me/ca/integration/api-errors.md) enumera tots els estats, cossos i codis.***## Claus d'API amb àmbitDona a cada servei o soci la seva pròpia clau en lloc de compartir la principal.
Cada clau té el seu propi accés: cap, lectura o escriptura per a cada recurs (sessions, decisions, fitxers multimèdia, persones, empreses, transaccions, fluxos de treball, webhooks, configuració de l'aplicació, analítica), i límits opcionals a determinats fluxos de treball, només a sessions aprovades, a una llista d'adreces IP i a una data de caducitat.
Pots rotar una clau amb un solapament de 24 hores i revocar-la immediatament.Les claus creades abans que existís l'accés amb àmbit definit mantenen l'accés complet.Consulta [Claus d'API](https://docs.didit.me/ca/console/api-keys.md) per veure els valors predefinits, els recursos que cobreix cadascun i com respon l'API a una clau amb àmbit definit.> [!TIP]
>
> Si reps un error `401`, torna a comprovar que estiguis utilitzant la clau d'API correcta per a l'Aplicació adequada i que no s'hagi regenerat.


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