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

# Autenticazione API: richieste API KYC sicure

> Autentica le chiamate API di Didit con una chiave nell'intestazione x-api-key. Chiavi errate o scadute restituiscono 401, assenti 403.



Prompt per l'autenticazione API
        Copia il prompt negli appunti



      
      

\<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>



      
      

Incolla in

## Trovare la tua chiave APIIn Didit, le chiavi API sono limitate a una specifica **Applicazione** all'interno del tuo account. Un'Applicazione è uno spazio di lavoro in cui puoi configurare workflow e gestire le verifiche per un determinato progetto o ambiente.Ogni Applicazione riceve una chiave API primaria con accesso completo al momento della creazione. Puoi aggiungere altre chiavi accanto ad essa, ciascuna con il solo accesso necessario per il servizio o il partner. Per trovare le tue chiavi:**1. Accedi alla Business Console**Vai alla [**Didit Business Console**](https://business.didit.me) e accedi.**2. Seleziona la tua Applicazione**Scegli l'**Applicazione** con cui desideri lavorare dal menu a discesa in alto.**3. Apri le chiavi API**Accedi a **Developers -> API keys** nella barra laterale sinistra.**4. Copia o crea una chiave**La chiave **Primaria** è il segreto dell'Applicazione stessa. Crea una nuova chiave per fornire a un servizio o partner un segreto dedicato, con l'accesso necessario.> [!WARNING]
>
> **La tua chiave API è un segreto: trattala come una password.**
>
> La chiave primaria fornisce accesso completo all'API per conto della tua Applicazione. Non esporla mai nel codice frontend, in repository pubblici o in bundle lato client. Mantienila sempre esclusivamente lato server.### Formato delle chiavi APILe nuove chiavi API iniziano con `sk_live_` per un'applicazione di produzione o con `sk_test_` per un'applicazione sandbox, seguiti da 43 caratteri compatibili con gli URL (lettere, cifre, `-` e `_`).
Le chiavi create prima di questo formato non hanno prefisso e continuano a funzionare senza modifiche.
Invia l'intera chiave, prefisso incluso, nell'intestazione `x-api-key`, e non rifiutare una chiave solo perché è priva di prefisso.## Trovare il tuo ID organizzazioneIl tuo **ID organizzazione** è l'UUID che identifica la tua organizzazione. Lo utilizzi nei percorsi API con ambito a livello di organizzazione come `/auth/v2/organizations/me/{org_id}/applications/`. Puoi copiarlo direttamente dalla Business Console, senza necessità di effettuare chiamate API:**1. Apri le impostazioni dell'organizzazione**Nella [**Didit Business Console**](https://business.didit.me), vai su **Impostazioni organizzazione**.**2. Copia l'ID organizzazione**Il campo **ID organizzazione** mostra l'UUID della tua organizzazione accanto al relativo nome, con un pulsante per copiarlo negli appunti.***## Eseguire richieste autenticatePer autenticare una richiesta API, includi la tua chiave API segreta nell'intestazione HTTP `x-api-key`.Ecco un esempio di richiesta autenticata all'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"
}
'
```***## Gestione degli erroriSe la tua chiave API è errata, malformata o revocata, l'API restituisce `401 Unauthorized`:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Una chiave scaduta restituisce anch'essa `401`, con `"detail": "This API key has expired."`.
Una richiesta priva di chiave restituisce `403` con `"detail": "You do not have permission to perform this action."`.| Codice di stato | Significato |
| - | - |
| **401** | La chiave API è errata, malformata, revocata o scaduta |
| **403** | Non è stata inviata alcuna chiave API, la chiave non ha accesso alla risorsa o all'azione richiesta, oppure la richiesta proviene da un indirizzo esterno all'elenco di indirizzi della chiave |
| **403** con `"code": "application_deleted"` | La chiave appartiene a un'applicazione che è stata eliminata. L'API risponde in questo modo per alcuni minuti dopo l'eliminazione, dopodiché rifiuta la chiave come qualsiasi altra chiave non valida. Non riprovare: l'applicazione e le sue chiavi non esistono più. |
| **404** | Su una rotta di sessione: la sessione non rientra nei workflow o negli stati previsti per la chiave |La pagina sugli [errori API](https://docs.didit.me/it/integration/api-errors.md) elenca ogni stato, corpo e codice.***## Chiavi API con ambito limitatoAssegna a ciascun servizio o partner una chiave dedicata invece di condividere quella primaria.
Ciascuna chiave ha il proprio accesso: nessuno, lettura o scrittura per ogni risorsa (sessioni, decisioni, media, persone, aziende, transazioni, workflow, webhook, impostazioni dell'applicazione, analisi), oltre a limitazioni facoltative per alcuni workflow, per le sole sessioni approvate e per un elenco di indirizzi IP, nonché a una data di scadenza.
Puoi ruotare una chiave con una sovrapposizione di 24 ore e revocarla immediatamente.Le chiavi create prima dell'introduzione dell'accesso con ambito limitato mantengono l'accesso completo.Consulta [Chiavi API](https://docs.didit.me/it/console/api-keys.md) per i preset, le risorse coperte da ciascuno di essi e il modo in cui l'API risponde quando viene utilizzata una chiave con ambito limitato.> [!TIP]
>
> Se ricevi un errore `401`, verifica di utilizzare la chiave API corretta per l'Applicazione giusta e che non sia stata rigenerata.


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