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

# Programmatische Registrierung: KYC-API für KI-Agenten

> Registrieren Sie sich bei Didit und erhalten Sie API-Schlüssel in 2 API-Aufrufen ohne Browser – ideal für KI-Agenten wie Cursor, Claude und Devin.

## Übersicht

Didit ist die **agentenfreundlichste Plattform für die Identitätsverifizierung**. KI-Coding-Agenten (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) können sich registrieren, Workflows konfigurieren und mit der Verifizierung von Identitäten beginnen – vollständig programmatisch, ohne jemals einen Browser zu öffnen.

**Warum Agenten Didit lieben:**

* **2 API-Aufrufe** von null bis zu den Anmeldedaten (register + verify-email).
* **Kein Browser erforderlich** – vollständig ohne Benutzeroberfläche, ideal für CI/CD- und Agenten-Workflows.
* **Kein zweiter Faktor bei einem neuen API-Konto:** Tokens werden direkt nach der E-Mail-Verifizierung zurückgegeben.
* **Automatisch bereitgestellte** Organisation und Anwendung mit `api_key` in der Antwort auf die Verifizierung.
* **Vollständige Verwaltungs-API** – Workflows, Fragebögen, Listen und Abrechnung konfigurieren, alles per API.
* **MCP-Server** verfügbar – Agenten können Didit-Tools nativ erkennen und nutzen.

Der vollständige Vertrag ist als [openapi-auth.json](https://docs.didit.me/openapi-auth.json) veröffentlicht; die folgenden Endpoints wurden dagegen abgeglichen.

## Basis-URL

Alle Endpoints in diesem Leitfaden befinden sich auf dem **Auth-Host**:

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

Dies ist ein anderer Host als der für die Verifizierungs-API (`https://verification.didit.me/v3`). Der Auth-Host stellt JWT-Access-Tokens aus und verwaltet Anwendungen. Der Verifizierungs-Host verarbeitet Sitzungen und führt AML-Prüfungen, Workflows usw. aus, authentifiziert mit dem langlebigen `api_key`, den Sie aus diesem Ablauf erhalten.

## Schnellstart

> [!WARNING]
>
> **Verwenden Sie eine echte, zustellbare E-Mail-Adresse.** Der Endpoint sendet den Verifizierungscode synchron, sodass reservierte Test-Domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) bei der E-Mail-Zustellung abgelehnt werden und der Aufruf einen `500` zurückgibt. Ersetzen Sie den Platzhalter `you@yourdomain.com` unten durch einen Posteingang, auf den Sie Zugriff haben.

### Schritt 1: Registrieren

```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"}'
```

**Antwort** (`201 Created`):

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

Ein 6-stelliger alphanumerischer Verifizierungscode (z. B. `A3K9F2`) wird per E-Mail an die Adresse gesendet. **Der Code läuft 10 Minuten nach dem Versand ab** – wenn er abgelaufen ist, rufen Sie diesen Endpoint erneut mit derselben E-Mail-Adresse und demselben Passwort auf: Bei einem noch nicht verifizierten Konto gibt er `200` mit `"A new verification code has been sent to your email."` und einem frischen Code zurück. Ein dedizierter `POST /programmatic/resend-otp/`-Endpoint (Body: `{"email", "password"}`) sendet den Code ebenfalls erneut, mit einer 60-Sekunden-Abklingzeit zwischen den Sendevorgängen; beide Routen unterliegen demselben Registrierungs-Rate-Limit unten.

### Schritt 2: Code verifizieren und Anmeldedaten abrufen

```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"}'
```

**Antwort** (`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"
  }
}
```

Sie haben nun alles, was Sie benötigen. Speichern Sie `application.api_key` sicher und senden Sie ihn als `x-api-key`-Header bei jedem Aufruf der Verifizierungs-API mit.

> [!NOTE]
>
> Tokens sind **RS256-signierte JWTs**. `expires_in` ist standardmäßig auf **86400 Sekunden (24 Stunden)** gesetzt. Das Access-Token wird nur für die Verwaltungs-Endpoints auf `apx.didit.me/auth/v2` benötigt – der Traffic der Verifizierungs-API auf `verification.didit.me/v3` wird mit dem langlebigen `api_key` authentifiziert, nicht mit dem JWT.

### Schritt 3: API verwenden

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

## Nachfolgende Anmeldungen

Tauschen Sie auf jedem künftig verwendeten Rechner Ihre E-Mail-Adresse und Ihr Passwort gegen ein neues JWT ein:

```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"}'
```

Gibt direkt `access_token` + `refresh_token` zurück – kein Browser erforderlich. Rufen Sie von dort aus `GET /organizations/me/` auf, um Ihre `org_id` (die `uuid` der Organisation) zu ermitteln, dann `GET /organizations/me/{org_id}/applications/`, um die Anwendungen der Organisation aufzulisten (die `uuid` jedes Eintrags ist eine `app_id`), und schließlich `GET /organizations/me/{org_id}/applications/{app_id}/`, um den `api_key` abzurufen.

> [!NOTE]
>
> Über die Konsole erstellte E-Mail/Passwort-Konten können `POST /programmatic/login/` ebenfalls verwenden, sobald die E-Mail-Adresse verifiziert ist. Reine OAuth-Konsolenkonten müssen vor der Verwendung dieses Login-Endpoints ohne Benutzeroberfläche ein Passwort festlegen.

### Wenn bei der Anmeldung mehr erforderlich ist

`POST /programmatic/login/` gibt Tokens nur zurück, wenn das Konto keinen zweiten Faktor hat.
Drei weitere Antworten sind möglich, und ein Agent, der die Anmeldung per Skript steuert, sollte diese verarbeiten:

| Konto | Antwort |
| - | - |
| Hat eine Authenticator-App oder einen Passkey | `200` mit `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` und ohne Tokens |
| Seine Organisation erzwingt SSO | `403` mit `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| Wurde wiederhergestellt und hat noch keine Anmeldemethode | `403` mit `"code": "recovery_setup_required"`, und ein Link zum Einrichten wird an die Adresse des Kontos gesendet |

Ein API-Schlüssel erfordert keine Anmeldung. Verwenden Sie daher einen solchen für alle automatisierten Abläufe: Ein Konto mit einem zweiten Faktor kann die Anmeldung über diesen Endpoint nicht abschließen.

## Passwortanforderungen

Serverseitig erzwungen, **eine Regel nach der anderen** – der erste Fehler bricht vorzeitig mit einem reinen Array-Fehler wie `["Password must contain at least one uppercase letter."]` ab. (Andere Validierungsfehler an diesem Endpoint verwenden die feldspezifische `{"password": [...]}`-Struktur. Das reine Array-Format bei Regeln zur Passwortstärke ist eine bekannte serverseitige Inkonsistenz; behandeln Sie es im Client-Code wie `{"password": [...]}`.)

| Regel | Detail |
| - | - |
| Mindestlänge | 8 Zeichen |
| Großbuchstabe | Mindestens ein `A–Z` |
| Kleinbuchstabe | Mindestens ein `a–z` |
| Ziffer | Mindestens eine `0–9` |
| Sonderzeichen | Mindestens eines von `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## Rate-Limits und Sperren

Drei unabhängige Kontrollmechanismen schützen den Auth-Host. Jeder davon kann eine `429`-Antwort auslösen; der `Retry-After`-Response-Header gibt an, wie lange Sie warten müssen.

| Bereich | Limit |
| - | - |
| Registrierung | **5** Versuche pro **IP** pro **Stunde** (geteilt mit `POST /programmatic/resend-otp/`). |
| E-Mail-Verifizierung | **10** Code-Versuche pro **E-Mail** pro **Stunde** und **50** pro Quell-**IP** pro **Stunde**, zuzüglich exponentiellem Backoff zwischen den Versuchen (30 s, Verdopplung pro Fehlschlag, begrenzt auf 1 Stunde). |
| Login (IP) | **20** Versuche pro **IP** pro **Minute** und **100** pro **IP** pro **Stunde**. |
| Login (E-Mail) | Progressive Sperre für das Konto: **5** aufeinanderfolgende Fehlschläge → 15 Min. Sperre; **10** → 1 Stunde; **20** → 24 Stunden. |

Ein `429`-Body sieht wie folgt aus:

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

Rate-Limits der Verification API (z. B. 600 Sitzungen/Min.) sind unabhängig und unter [Rate-Limits](https://docs.didit.me/de/integration/rate-limiting.md) dokumentiert.

## Anwendungen verwalten

Sobald Sie authentifiziert sind, können Sie Anwendungen innerhalb Ihrer Organisation abrufen, erstellen oder aktualisieren.

Dies eignet sich ideal für **Reseller**, die eine Anwendung pro Kunde wünschen. Jede Anwendung hat ihre eigene `client_id`, ihren eigenen `api_key`, eigene Metadaten und Einstellungen. Es ist auch nützlich, wenn Ihre Organisation unterschiedliche Produkte, Marken, Regionen, Umgebungen oder Anwendungsfälle voneinander trennen möchte.

```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"
  }'
```

Das Auflisten, Erstellen oder Aktualisieren von Anwendungen erfordert, dass der Benutzer **owner** oder **admin** der Zielorganisation ist; andernfalls lautet die Antwort `403`.

## Was können Agenten nach der Registrierung tun?

Mit dem `api_key` haben Agenten vollen Zugriff auf die Verification API. Auditierte Pfade auf `https://verification.didit.me/v3`:

| API | Funktion |
| - | - |
| `POST /v3/session/` | Verifizierungssitzung erstellen. |
| `GET /v3/sessions/` | Sitzungen auflisten. |
| `GET /v3/session/{id}/decision/` | V3-Entscheidung abrufen (Arrays im Plural – siehe Datenmodelle). |
| `GET /v3/workflows/` | Verifizierungs-Workflows auflisten. |
| `GET /v3/questionnaires/` | Benutzerdefinierte Fragebögen auflisten. |
| `GET /v3/users/` | Endbenutzer auflisten (indiziert nach `vendor_data`). |
| `GET /v3/billing/balance/` | Credit-Guthaben prüfen. |
| `POST /v3/billing/top-up/` | Credits aufladen. |
| `GET /v3/webhook/destinations/` | Webhook-Ziele verwalten (auflisten / erstellen / aktualisieren / löschen). |

Den vollständigen Umfang finden Sie in der [Management-API-Referenz](https://docs.didit.me/de/sessions-api/management-api.md).

## MCP-Server-Integration

Für die bestmögliche Agentenerfahrung nutzen Sie den gehosteten Didit-MCP-Server unter `https://mcp.didit.me/mcp`. Er benötigt keinen API-Schlüssel: Bei der ersten Verbindung öffnet Ihr Client einen Browser, Sie klicken auf **Mit Didit anmelden** (OAuth 2.1 mit PKCE) und der Server agiert in Ihrem Namen mit den Berechtigungen Ihrer Console-Rolle. Clients mit nativer Unterstützung für Remote-MCP (Cursor, VS Code) nutzen diesen Eintrag; Claude Web und Desktop fügen ihn als benutzerdefinierten Connector hinzu:

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

Claude Code: `claude mcp add --transport http didit https://mcp.didit.me/mcp`. Clients, die nur stdio unterstützen (Windsurf, Zed), nutzen die `mcp-remote`-Bridge, die den OAuth-Flow für Sie ausführt.

Der API-Schlüssel, den Sie aus dem obigen Registrierungs-Flow erhalten, dient zum Aufrufen der REST-API von Ihrem eigenen Backend aus; der MCP verwendet ihn nie. Weitere Details finden Sie in der [MCP-Übersicht](https://docs.didit.me/de/integration/mcp/overview.md) und der [Installation pro Client](https://docs.didit.me/de/integration/mcp/installation.md).

## Referenz zur Fehlerstruktur

Alle `apx.didit.me/auth/v2`-Endpoints teilen sich dieselben drei Antwortstrukturen (siehe `openapi-auth.json`):

* **Validierung auf Feldebene** — `{"field": ["message", ...]}` mit HTTP `400`.
* **Validierung auf Formularebene** (insbesondere Passwortstärke und Verifizierungscode-Fehler) — einfaches Array `["Invalid or expired verification code."]` mit HTTP `400`.
* **Authentifizierung / Geschäftsregel** — `{"detail": "..."}` mit `400`, `401`, `403`, `404` oder `429`. `429`-Antworten enthalten einen `Retry-After`-Response-Header, der angibt, wie lange Sie warten müssen (der Body enthält nur `detail`).

Der Verification-Host gibt Fehler als `{"detail": "..."}` zurück und 429-Antworten enthalten `X-RateLimit-*` und `Retry-After` – siehe [Rate-Limits](https://docs.didit.me/de/integration/rate-limiting.md).


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