Authentifizierung

Jede Anfrage an die Certivant-API authentifiziert sich mit einem API-Schlüssel — einem langlebigen Bearer-Token, das auf eine einzelne Organisation beschränkt ist. Sitzungen und Cookies sind für das Dashboard gedacht; die API verwendet sie nie.

Format des Headers

Authorization: Bearer ck_live_NjV3aXJWN0RpZ2tRZ1JLWEcxc1V2eEgwUjg...

• Der Header-Name lautet Authorization.
• Das Schema ist Bearer (ein Leerzeichen, danach der Schlüssel).
• Der Schlüssel beginnt mit ck_live_ (Produktion) oder ck_test_ (Test). Ältere Schlüssel, die mit kyk_ beginnen, funktionieren unverändert weiter.

Jede Antwort eines schlüsselgeschützten Endpunkts enthält X-Certivant-Environment: live|test. Testschlüssel kennzeichnen die Nutzung nur; sie isolieren die Daten nicht (siehe Live- vs. Testschlüssel).

Wenn der Schlüssel fehlt, unbekannt, widerrufen, abgelaufen oder rotiert ist, antwortet Certivant mit HTTP 401 und error.code = "UNAUTHORIZED". error.reason ist ein stabiler Unterkode:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "api_key_expired",
    "message": "This API key has expired. Create or rotate a key."
  }
}

Woher die Schlüssel kommen

API-Schlüssel werden im Dashboard unter KYC → Entwickler erstellt. Sie müssen Inhaber oder Administrator der Organisation sein. Der Schlüssel wird nur einmal angezeigt, unmittelbar nach der Erstellung — Certivant speichert einen SHA-256-Hash, deshalb können wir ihn nicht erneut anzeigen. Falls Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Das Dashboard listet jeden Schlüssel (anhand seines 8-stelligen Präfixes) zusammen mit seinen Berechtigungsbereichen, dem Zeitstempel der letzten Nutzung und der Anzahl der Aufrufe. Sie können einen Schlüssel jederzeit widerrufen; der Widerruf wirkt sofort und ist nicht umkehrbar.

Berechtigungsbereiche

Berechtigungsbereiche sind additiv. Beim Erstellen eines Schlüssels können Sie eine beliebige Teilmenge vergeben. Eine Anfrage an einen Endpunkt, für den Sie den erforderlichen Berechtigungsbereich nicht besitzen, liefert HTTP 403 mit error.code = "FORBIDDEN" und error.reason = "insufficient_scope"; die Meldung nennt jeden Berechtigungsbereich, der akzeptiert worden wäre.

Standard-Berechtigungsbereiche

Ressourcenbezogene Berechtigungsbereiche

Für das Prinzip der minimalen Rechte können Sie stattdessen Berechtigungsbereiche der Form <resource>:<action> vergeben. Jeder davon wird auf den Endpunkten seiner eigenen Ressource zusätzlich zum passenden Standard-Berechtigungsbereich akzeptiert und reicht nie über diese Ressource hinaus.

Beispiele: forms:write erlaubt einem Schlüssel POST /v1/kyc/forms/:formId/send, aber nicht das Erstellen von Verifizierungsanfragen; verifications:read + analytics:read ergibt einen reinen Lese-Schlüssel für ein Dashboard. <resource>:manage umfasst jede andere Aktion auf dieser Ressource.

Beschränkungen

Neben den Berechtigungsbereichen können Sie einen Schlüssel beim Erstellen oder Bearbeiten einschränken:

• Formulare — der Schlüssel darf nur die von Ihnen gewählten Formulare verwenden und nur Verifizierungen erreichen, die über diese Formulare erstellt wurden. Siehe Formularbeschränkung.
• Workflows — der Schlüssel darf nur die von Ihnen gewählten Automatisierungs-Workflows (nach Name) auslösen. Siehe Workflow-Beschränkung.
• IP-Allowlist — IPv4-/IPv6-Adressen und CIDR-Bereiche (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Eine Anfrage von einer anderen Adresse — oder deren Adresse nicht ermittelt werden kann — wird mit 403 ip_not_allowed abgelehnt.
• Ablauf — nach expiresAt liefert der Schlüssel 401 api_key_expired.

Alle Beschränkungen sind standardmäßig leer (unbeschränkt), und bestehende Schlüssel haben keine. Schlüssel, die vor Einführung der Beschränkungen erstellt wurden (kyk_…), sowie die Token des Connectors werden nie beschränkt.

Formularbeschränkung

Ein auf die Formulare X und Y beschränkter Schlüssel ist auf diese Formulare und auf die über sie erstellten Verifizierungen begrenzt. Eine Verifizierung gilt als „über ein Formular erstellt“, wenn sie mit POST /v1/kyc/forms/:formId/send versendet (von einem beliebigen Schlüssel oder aus dem Dashboard), über den öffentlichen Link des Formulars eingereicht oder mit POST /v1/kyc/requests und einer formId erstellt wurde.

Eine Erneuerung oder eine UBO-Verifizierung, die durch eine Unternehmensverifizierung ausgelöst wird, gehört zu demselben Formular wie die Verifizierung, aus der sie stammt.

Workflow-Beschränkung

Certivant hat keinen Endpunkt, der einen Workflow per Name angibt; diese Beschränkung führt daher bei keinem Aufruf zu einem 403. Sie steuert, welche Automatisierungs-Workflows für die vom Schlüssel erstellten Verifizierungen laufen dürfen:

• Jede Verifizierung, die der Schlüssel erstellt (POST /v1/kyc/requests, /requests/batch, POST /v1/kyc/forms/:formId/send, POST /v1/kyc/conferences mit einem eingebetteten Antragsteller), vermerkt den Schlüssel, von dem sie stammt.
• Ab dann dürfen für genau diese Verifizierung nur die Workflows laufen, deren Name auf der Liste des Schlüssels steht — unabhängig davon, was das Ereignis auslöst: der Antragsteller, der das Formular einreicht, eine Entscheidung, ein Prüfer, ein Webhook oder der Schlüssel selbst. Ereignisgesteuerte Ausführungen anderer Workflows werden übersprungen, ebenso ein Workflow, den ein anderer Workflow über einen Schritt Workflow auslösen startet.
• Die aktuelle Liste des Schlüssels gilt, solange der Schlüssel existiert. Eine Verschärfung oder Aufhebung der Beschränkung wirkt daher sofort auf laufende Verifizierungen. Wird der Schlüssel gelöscht, gilt weiterhin die Liste, die er beim Erstellen der Verifizierung hatte.
• Verifizierungen, die aus dem Dashboard, durch einen Antragsteller über ein öffentliches Formular oder durch einen Schlüssel ohne Workflow-Beschränkung erstellt wurden, sind davon nicht betroffen, ebenso wenig andere Auslöser (Zeitpläne, andere Verifizierungen).
• Eine Erneuerung und die UBO-Verifizierungen eines Unternehmens übernehmen die Beschränkung der Verifizierung, aus der sie stammen.

Der Fehlergrund workflow_not_allowed ist für Endpunkte reserviert, die einen Workflow per Name entgegennehmen; einen solchen Endpunkt gibt es derzeit nicht.

Live- vs. Testschlüssel

Schlüssel ck_live_… sind für die Produktion gedacht, Schlüssel ck_test_… für Entwicklung und CI. Die Umgebung ist eine Kennzeichnung, keine Sandbox: Antworten tragen X-Certivant-Environment, das Dashboard zeigt das Badge an, und Audit-Einträge halten das Schlüsselpräfix fest — ein Testschlüssel liest und schreibt jedoch dieselben Daten wie ein Live-Schlüssel. Die einzige Sandbox ist die Sandbox auf Mandantenebene: Bis Certivant Ihre Organisation verifiziert hat, sind Live-Verifizierungsfunktionen für jeden Schlüssel gesperrt. Verwenden Sie eine eigene Organisation, wenn Sie vollständig getrennte Testdaten benötigen.

Empfohlene Hygiene für Umgebungen

• Ein Schlüssel pro Umgebung. Erstellen Sie getrennte Schlüssel für local, staging und production. Wird eine Umgebung kompromittiert, bleiben die anderen beiden sicher.
• Schlüssel aussagekräftig benennen. payments-service-prod-2026Q2 ist besser als key1. Die Bezeichnung erscheint im Audit-Protokoll.
• Ablaufdatum setzen für Schlüssel, die Sie nur vorübergehend benötigen — für Migrationen, Demos oder Zugriff durch Dritte. Certivant lehnt den Schlüssel automatisch ab, sobald expiresAt überschritten ist.
• Jährlich rotieren. Erstellen Sie einen neuen Schlüssel, stellen Sie Ihren Dienst darauf um und widerrufen Sie den alten, sobald der neue Schlüssel den Datenverkehr fehlerfrei verarbeitet hat.
• Schlüssel niemals in Git committen. Verwenden Sie Ihren Geheimnisspeicher — AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical oder zumindest .env-Dateien, die in .gitignore stehen.

Rotation ohne Ausfallzeit

Verwenden Sie Rotieren beim Schlüssel (Entwickler → API-Schlüssel) oder die API:

POST /api/kyc/api-keys/{id}/rotate        (dashboard session, api.access permission)
{ "overlapHours": 24 }

sequenceDiagram
  participant You
  participant Dashboard
  participant Service
  participant Certivant
  You->>Dashboard: Rotate key (overlap 24 h)
  Dashboard-->>You: ck_live_new_… (same scopes, restrictions, IP allowlist)
  You->>Service: Deploy with new key in env var
  Service->>Certivant: Authenticated requests with new key
  Note over Certivant: Old key still works until the overlap ends
  Certivant-->>Service: Old key → 401 api_key_rotated after the overlap

1. Rotieren Sie den Schlüssel. Der Ersatz übernimmt Bezeichnung, Berechtigungsbereiche, Beschränkungen, IP-Allowlist und Ablaufdatum; sein vollständiger Wert wird einmal angezeigt.
2. Stellen Sie Ihren Dienst während der Überlappung (0–168 Stunden, Standard 24) mit dem neuen Schlüssel bereit. Der alte Schlüssel funktioniert bis dahin weiter, und sein Zeitstempel Zuletzt verwendet im Dashboard zeigt, ob noch etwas damit aufruft.
3. Nach Ende der Überlappung liefert der alte Schlüssel 401 api_key_rotated. Verwenden Sie overlapHours: 0, um ihn sofort zu widerrufen. Sie können ihn auch früher manuell widerrufen.

Was passiert, wenn ein Schlüssel widerrufen wird

Die nächste Anfrage mit dem widerrufenen Schlüssel liefert 401. Es gibt keine Schonfrist. Falls Sie versehentlich einen Schlüssel widerrufen, den Sie noch benötigen, erstellen Sie einen neuen — ein Widerruf lässt sich nicht rückgängig machen.

Öffentliche Endpunkte (kein Schlüssel nötig)

Eine kleine Gruppe von Endpunkten ist bewusst öffentlich — sie benötigen keinen API-Schlüssel:

• GET /api/health und GET /api/status — Betriebsprüfungen.
• GET /api/branding — öffentliche Branding-Konfiguration für die gehostete Oberfläche.
• GET /api/kyc/public/status?ref=… — Abfrage des Status eines Antragstellers über eine externe Referenz.
• GET /api/kyc/public/forms/:slug und die Endpunkte zum Einreichen von Formularen — von der gehosteten Formularoberfläche verwendet.

Diese sind der Vollständigkeit halber dokumentiert, aber die meisten Integrationen rufen sie nie direkt auf — die URL der gehosteten Sitzung übernimmt jede öffentliche Interaktion.

Audit-Protokollierung

Jeder authentifizierte API-Aufruf wird in KycAuditLog mit dem Schlüsselpräfix des Aufrufers, dem Endpunkt und dem Akteurstyp (api) festgehalten. Den Verlauf können Sie im Dashboard unter KYC → Audit-Protokoll einsehen. Audit-Einträge werden für die gesamte Lebensdauer der jeweiligen Anfrage aufbewahrt.