Live-ID-API-Referenz

Drei Bereiche: Schlüsselverwaltung (über das Dashboard authentifiziert, Administratoren), der Sitzungslebenszyklus (über Schlüssel bzw. Sitzungstoken authentifiziert, öffentlich) und der Webhook. Die unten genannte Basis-URL ist der Host Ihres Mandanten.

Einen Identifikationsschlüssel ausstellen

POST /api/kyc/live-id/:orgSlug/keys    Authentifizierung: Dashboard-Sitzung (Administrator/Inhaber)

Stellt einen Schlüssel pro Profil aus. Der Klartext-Token wird einmal zurückgegeben — speichern Sie ihn sicher auf Ihrem Backend; nur sein Hash wird aufbewahrt.

Anfrage-Body

{ "applicantId": "app_…", "label": "mobile-app", "expiresInDays": 365 }

Antwort 201

{
  "id": "lik_…",
  "token": "livid_…",          // shown ONCE
  "keyVersion": 1,
  "label": "mobile-app",
  "expiresAt": null,
  "createdAt": "2026-06-18T12:00:00.000Z"
}

Zugehörige Endpunkte: GET /api/kyc/live-id/:orgSlug/keys (Liste, nur Metadaten), DELETE /api/kyc/live-id/:orgSlug/keys/:id (widerrufen), GET /api/kyc/live-id/:orgSlug/enrollments (Liste der registrierten Profile).

Eine Sitzung erzeugen

POST /api/kyc/public/live-id/sessions    Authentifizierung: Identifikationsschlüssel (im Body)

Rufen Sie dies serverseitig auf. Prüft den Schlüssel, wendet das Abrechnungs-Gate an und erzeugt ein einmal verwendbares Sitzungstoken.

Anfrage-Body

{ "key": "livid_…", "deviceFingerprint": "optional", "captureMethod": "live_camera" }

Antwort 201

{
  "sessionId": "lis_…",
  "sessionToken": "…",
  "expiresAt": "2026-06-18T12:02:00.000Z",
  "captureUrl": "https://app.certivant.com/live-id/…",
  "nonce": "…"
}

Übergeben Sie captureUrl an das Gerät. Das sessionToken wird ebenfalls zurückgegeben, damit Sie den Status serverseitig abfragen können. nonce ist der einmalige Wert der Sitzung — er wird nur benötigt, wenn Sie Ihre eigene Aufnahmeoberfläche bauen (siehe Selfie übermitteln).

Die Erzeugung wird mit 429 enrollment_locked abgelehnt, solange das Profil nach wiederholten fehlgeschlagenen Validierungen gesperrt ist (5 Fehlschläge innerhalb von 15 Minuten sperren es für 30 Minuten und lösen live_id.enrollment.locked aus).

Die Aufnahmeseite öffnen

GET /live-id/:sessionToken    Authentifizierung: Sitzungstoken (im Pfad)

Die gehostete, für Mobilgeräte optimierte Aufnahmeseite — öffnen Sie sie auf oberster Ebene: in einem Popup, per Weiterleitung oder in einer nativen WebView. Sie wird mit frame-ancestors 'none' ausgeliefert, ist also nicht per iframe einbettbar. Sie zeigt die Oberfläche für Kamera und Selfie, solange die Sitzung aktiv ist, und einen klaren Hinweis, wenn sie abgelaufen, ungültig oder bereits abgeschlossen ist.

Beim Laden ruft die gehostete Seite POST /api/kyc/public/live-id/sessions/:sessionToken/open auf. Dies erfasst die IP-Adresse des Geräts und liefert den einmaligen Wert der Sitzung zurück, den die Seite zusammen mit dem Selfie zurücksendet. Ab diesem Punkt wird ein Selfie ohne den richtigen Wert abgelehnt.

Eine Aufnahme öffnen (nur für eigene Aufnahmeoberfläche)

POST /api/kyc/public/live-id/sessions/:sessionToken/open    Authentifizierung: Sitzungstoken (im Pfad)

Rufen Sie dies vom Gerät aus auf, sobald Ihr eigener Aufnahmebildschirm geöffnet wird. Antwort 200:

{ "nonce": "…", "expiresAt": "2026-06-18T12:02:00.000Z" }

Selfie übermitteln

POST /api/kyc/public/live-id/validate    Authentifizierung: Sitzungstoken (im Body)

Die gehostete Seite ruft dies für Sie auf. Dokumentieren Sie es nur, wenn Sie statt der gehosteten Seite eine eigene native Aufnahmeoberfläche bauen.

Anfrage-Body

{ "sessionToken": "…", "selfieImage": "data:image/jpeg;base64,/9j/4AAQ…", "nonce": "…" }

selfieImage akzeptiert eine Base64-Zeichenkette oder eine data:-URL. Mindestens etwa 1 KB, höchstens 8 MB.

nonce ist der einmalige Wert der Sitzung (aus der Antwort auf die Erzeugung oder aus /open):

• Ein falscher Wert wird immer abgelehnt (reason: "nonce_mismatch", matched: false).
• Ein fehlender Wert wird nur abgelehnt, wenn die Aufnahme über /open geöffnet wurde (die gehostete Seite tut dies immer). Server-zu-Server-Integrationen, die /open nie aufrufen, funktionieren weiterhin ohne ihn — das Mitsenden wird jedoch empfohlen.

Dasselbe Selfie kann nie zweimal verwendet werden: Eine exakte Kopie des registrierten Referenzfotos oder des Selfies einer früheren Sitzung wird abgelehnt (reason: "replayed_image"). Nahezu identische Kopien werden in den riskSignals des Webhooks gemeldet.

Antwort 200

{
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "livePassed": true,
  "reason": "matched",
  "sessionId": "lis_…"
}

reason ist einer der Werte matched, face_below_threshold, liveness_failed, face_and_liveness_failed, no_reference_image, nonce_mismatch, replayed_image, near_duplicate_image.

Eine Sitzung abfragen

GET /api/kyc/public/live-id/sessions/:sessionToken    Authentifizierung: Sitzungstoken (im Pfad)

Antwort 200

{
  "sessionId": "lis_…",
  "status": "completed",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "reason": "matched",
  "expiresAt": "2026-06-18T12:02:00.000Z"
}

status: pending → processing → completed (oder expired). Ist der Status completed, gibt matched das Ergebnis an. Fragen Sie etwa alle 2 Sekunden ab; beenden Sie die Abfrage bei completed oder expired.

Webhook — live_id.validation.completed

Wird einmal pro abgeschlossener Validierung an die Webhook-URL Ihres Mandanten gesendet, und zwar genau wie jeder andere Certivant-Webhook signiert (X-Certivant-Signature-V2: t=…,v1=…; der ältere Header X-KYC-Signature: sha256=… wird weiterhin gesendet).

{
  "event": "live_id.validation.completed",
  "organizationId": "org_…",
  "validationId": "liv_…",
  "sessionId": "lis_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "decisionReason": "matched",
  "riskSignals": {
    "nearDuplicateImage": false,
    "nearestImageDistance": 0.21,
    "nearestImageSource": "previous_session",
    "nonceVerified": true,
    "deviceIpChanged": false
  },
  "timestamp": "2026-06-18T12:02:00.000Z"
}

riskSignals dienen Ihrer eigenen Risikoentscheidung — sie ändern matched allein nie. nonceVerified ist wahr, wenn das Selfie den einmaligen Wert der Sitzung trug; deviceIpChanged ist wahr, wenn sich die IP-Adresse des Geräts zwischen /open und dem Selfie geändert hat (null, wenn sich das nicht vergleichen lässt).

Webhook — live_id.enrollment.locked

Wird ausgelöst, wenn ein Profil nach wiederholten fehlgeschlagenen Validierungen gesperrt wird.

{
  "event": "live_id.enrollment.locked",
  "organizationId": "org_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "failures": 5,
  "lockedUntil": "2026-06-18T12:32:00.000Z",
  "timestamp": "2026-06-18T12:02:00.000Z"
}

Siehe Webhooks → Signaturprüfung.

Fehler