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

# API-Authentifizierung: Sichere KYC-API-Anfragen

> Didit-API-Anfragen über den x-api-key-Header authentifizieren. Falsche oder abgelaufene Schlüssel liefern 401, fehlende 403.



API-Authentifizierungs-Prompt
        Prompt in die Zwischenablage kopieren



      
      

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



      
      

Einfügen in

## API-Schlüssel findenIn Didit sind API-Schlüssel auf eine bestimmte **Anwendung** innerhalb Ihres Kontos beschränkt. Eine Anwendung ist ein Arbeitsbereich, in dem Sie Workflows konfigurieren und Verifizierungen für ein bestimmtes Projekt oder eine bestimmte Umgebung verwalten können.Jede Anwendung erhält bei ihrer Erstellung einen primären API-Schlüssel mit vollem Zugriff. Sie können daneben weitere Schlüssel hinzufügen, jeweils mit genau den Zugriffsrechten, die ein Dienst oder Partner benötigt. So finden Sie Ihre Schlüssel:**1. In der Business Console anmelden**Gehen Sie zur [**Didit Business Console**](https://business.didit.me) und melden Sie sich an.**2. Anwendung auswählen**Wählen Sie die **Anwendung**, mit der Sie arbeiten möchten, aus dem Dropdown-Menü oben aus.**3. API-Schlüssel öffnen**Navigieren Sie in der linken Seitenleiste zu **Entwickler -> API-Schlüssel**.**4. Schlüssel kopieren oder erstellen**Der **primäre** Schlüssel ist das Geheimnis der Anwendung. Erstellen Sie einen neuen Schlüssel, um einem Dienst oder Partner ein eigenes Geheimnis mit den erforderlichen Berechtigungen zuzuweisen.> [!WARNING]
>
> **Ihr API-Schlüssel ist ein Geheimnis – behandeln Sie ihn wie ein Passwort.**
>
> Der primäre Schlüssel bietet vollen Zugriff auf die API im Namen Ihrer Anwendung. Machen Sie ihn niemals im Frontend-Code, in öffentlichen Repositories oder clientseitigen Bundles öffentlich zugänglich. Bewahren Sie ihn stets ausschließlich serverseitig auf.### Format des API-SchlüsselsNeue API-Schlüssel beginnen mit `sk_live_` für eine Live-Anwendung oder `sk_test_` für eine Sandbox-Anwendung, gefolgt von 43 URL-sicheren Zeichen (Buchstaben, Ziffern, `-` und `_`).
Schlüssel, die vor diesem Format erstellt wurden, haben kein Präfix und funktionieren weiterhin unverändert.
Senden Sie den gesamten Schlüssel einschließlich Präfix im Header `x-api-key`, und weisen Sie einen Schlüssel nicht ab, weil er kein Präfix hat.## Organisations-ID findenIhre **Organisations-ID** ist die UUID, die Ihre Organisation identifiziert. Sie verwenden sie in organisationsbezogenen API-Pfaden wie `/auth/v2/organizations/me/{org_id}/applications/`. Sie können sie direkt aus der Business Console kopieren, ganz ohne API-Aufruf:**1. Organisationseinstellungen öffnen**Gehen Sie in der [**Didit Business Console**](https://business.didit.me) zu **Organisationseinstellungen**.**2. Organisations-ID kopieren**Das Feld **Organisations-ID** zeigt die UUID Ihrer Organisation neben dem Organisationsnamen an, zusammen mit einer Schaltfläche zum Kopieren in die Zwischenablage.***## Authentifizierte Anfragen sendenUm eine API-Anfrage zu authentifizieren, fügen Sie Ihren geheimen API-Schlüssel in den HTTP-Header `x-api-key` ein.Hier ist ein Beispiel für eine authentifizierte Anfrage an den 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"
}
'
```***## FehlerbehandlungWenn Ihr API-Schlüssel falsch, fehlerhaft formatiert oder widerrufen ist, gibt die API `401 Unauthorized` zurück:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```Ein abgelaufener Schlüssel gibt ebenfalls `401` zurück, mit `"detail": "This API key has expired."`.
Eine Anfrage ohne Schlüssel gibt `403` zurück mit `"detail": "You do not have permission to perform this action."`.| Statuscode | Bedeutung |
| - | - |
| **401** | Der API-Schlüssel ist falsch, fehlerhaft formatiert, widerrufen oder abgelaufen |
| **403** | Es wurde kein API-Schlüssel gesendet, der Schlüssel hat keinen Zugriff auf die angeforderte Ressource oder Aktion, oder die Anfrage kam von einer Adresse außerhalb der IP-Liste des Schlüssels |
| **403** mit `"code": "application_deleted"` | Der Schlüssel gehört zu einer Anwendung, die gelöscht wurde. Die API gibt dies für einige Minuten nach der Löschung zurück und weist den Schlüssel danach wie jeden ungültigen Schlüssel ab. Führen Sie keinen Wiederholungsversuch durch: Die Anwendung und ihre Schlüssel existieren nicht mehr. |
| **404** | Bei einer Sitzungs-Route: Die Sitzung liegt außerhalb der für den Schlüssel konfigurierten Workflows oder Status |Auf der Seite [API-Fehler](https://docs.didit.me/de/integration/api-errors.md) sind alle Statuscodes, Bodys und Codes aufgeführt.***## API-Schlüssel mit eingeschränktem ZugriffGeben Sie jedem Dienst oder Partner einen eigenen Schlüssel, anstatt den primären Schlüssel zu teilen.
Jeder Schlüssel verfügt für jede Ressource über eigene Zugriffsberechtigungen: keine, Lese- oder Schreibberechtigung (Sitzungen, Entscheidungen, Medien, Personen, Unternehmen, Transaktionen, Workflows, Webhooks, Anwendungseinstellungen, Analysen) sowie optionale Einschränkungen auf bestimmte Workflows, nur genehmigte Sitzungen, eine Liste von IP-Adressen und ein Ablaufdatum.
Sie können einen Schlüssel mit einer 24-stündigen Überschneidung rotieren und ihn sofort widerrufen.Schlüssel, die vor der Einführung eingeschränkten Zugriffs erstellt wurden, behalten vollen Zugriff.Unter [API-Schlüssel](https://docs.didit.me/de/console/api-keys.md) finden Sie die Voreinstellungen, die jeweils abgedeckten Ressourcen und Informationen dazu, wie die API auf einen Schlüssel mit eingeschränktem Zugriff reagiert.> [!TIP]
>
> Wenn Sie einen `401`-Fehler erhalten, prüfen Sie sorgfältig, ob Sie den richtigen API-Schlüssel für die richtige Anwendung verwenden und ob er nicht neu generiert wurde.


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