Entwickler — API-Schlüssel & REST-API

Was passiert hier?

Die REST-API von Certivant ermöglicht es Ihren eigenen Systemen, Verifizierungsanfragen anzulegen, Dokumente hochzuladen und den Status abzurufen, ohne das Dashboard zu nutzen. Es gibt zwei Hauptanwendungsfälle:

1. Verifizierung in den eigenen Onboarding-Ablauf einbetten. Ihr Anmeldeformular sendet die Daten an Ihr Backend, das Backend ruft Certivant auf, und der Antragsteller erhält einen Link zur gehosteten Prüfung von Certivant.
2. Verifizierungsstatus in Data Warehouse oder CRM synchronisieren. In Kombination mit Webhooks aktualisieren sich Ihre Systeme bei Statusänderungen.

Die Authentifizierung der API erfolgt über API-Schlüssel, die Sie im Dashboard ausstellen. Die vollständige Endpunkt-Dokumentation finden Sie unter /app/{your-org}/kyc/developer. Diese Seite behandelt die Verwaltung der Schlüssel und einen konzeptionellen Überblick.

Wo finden Sie es?

KYC → Entwickler in der linken Seitenleiste. (API-Schlüssel befanden sich früher unter den KYC/B-Einstellungen. Sie haben jetzt eine eigene Startseite für Entwickler.)

Das Entwicklerportal ist ein zentraler Bereich mit einem Menü auf der linken Seite:

• Übersicht & Schnellstart — Ihre Basis-URL, die Authentifizierung und eine Anfrage zum Kopieren in 8 Sprachen (cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#). Die Beispiele sind mit Ihrem echten Host und einem Platzhalter für Ihren Schlüssel vorausgefüllt.
• API-Schlüssel — Ihre Schlüssel auflisten, erstellen und widerrufen.
• Endpunkt-Referenz — jeder Endpunkt der Integration (/v1) mit Methode, Pfad, Scopes und Parametern, dazu ein Link zum interaktiven API-Playground.
• Webhook-Handler — fertige Handler mit Signaturprüfung in 6 Sprachen (siehe auch Webhooks).
• Ratenbegrenzung — das wirksame Limit Ihrer Organisation pro Minute, nur lesend angezeigt.
• FAQ — die Fragen, die Integratoren am häufigsten stellen.

API-Schlüssel ausstellen

Den Schlüssel verwenden

Senden Sie ihn im Header Authorization:

Authorization: Bearer ck_live_a3f...

Schlüssel, die vor dem Format ck_live_ / ck_test_ erstellt wurden (beginnend mit kyk_), funktionieren unverändert weiter.

Der schnellste Weg zu einer funktionierenden Integration:

curl https://api.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer $CV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "applicant": {
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Zuordnung zu Partnern und Unter-Mandanten

Wenn Sie Verifizierungen im Auftrag vieler Endkunden aus einer Organisation durchführen, etwa das klassische Partner- oder Reseller-Modell. Ein E-Signatur-Anbieter prüft zum Beispiel Unterzeichner für Hunderte Unternehmen. Dann brauchen Sie nicht für jeden Kunden eine eigene Organisation. Versehen Sie jede Anfrage beim Anlegen über die API mit zwei optionalen Feldern:

• subTenantName — der Anzeigename des Endkunden (z. B. „Acme Corp“).
• subTenantExternalId — Ihre interne ID für diesen Kunden (z. B. cust_8842).

Sobald Anfragen so markiert sind, können Sie:

• Den Listen-Endpunkt filtern nach subTenantExternalId (GET /api/v1/kyc/requests?subTenantExternalId=cust_8842).
• Webhooks weiterleiten — beide Felder werden in jedem Ereignis-Envelope zurückgegeben. Ihr Handler weiß so, zu welchem Kunden ein Ergebnis gehört, ohne eine Suche durchführen zu müssen.
• Die Dashboards filtern — Nutzung, Audit-Protokoll, Monitoring, Berichte und Analytik erhalten alle einen Filter Unter-Mandant, sobald eine Anfrage die Markierungen trägt. Die Listen für KYC/KYB können die Spalten Unter-Mandant und Externe ID anzeigen (standardmäßig ausgeblendet. Aktivieren Sie sie über das Spaltenmenü).

Die genaue Form der Anfrage finden Sie in der API-Referenz: KYC-Anfragen → Anfrage anlegen.

Ratenbegrenzung

Ihr Limit für API-Aufrufe pro Minute wird durch Ihren Tarif festgelegt. Übliche Standardwerte: 60 pro Minute im Tarif Launch, 300 pro Minute in Pro und Scale, 600 pro Minute in Enterprise. Die genaue Obergrenze für Ihre Organisation wird nur lesend auf der Seite Entwickler angezeigt. Jede API-Antwort enthält sie im Header X-RateLimit-Limit. Jeder Schlüssel wird unabhängig voneinander innerhalb dieser Obergrenze gezählt.

Überschreiten Sie das Limit, liefern Anfragen HTTP 429 Too Many Requests mit X-RateLimit-Reset (Sekunden bis zum Zurücksetzen des Fensters). Warten Sie und versuchen Sie es erneut.

Brauchen Sie eine höhere Obergrenze? Ihr Super-Administrator legt sie fest. Er kann Ihr Limit für den Kunden bis zur Obergrenze Ihres Tarifs anheben. Das geht unter Admin → Kunden → (Ihre Organisation) → Organisation bearbeiten. Eine höhere Obergrenze erfordert einen höheren Tarif. Das Limit wird vom Betreiber gesteuert. Mandanten können es sehen, aber nicht ändern. Details zur Funktionsweise finden Sie in der Entwicklerreferenz: Ratenbegrenzungen.

Sicherheitsempfehlungen

• Speichern Sie Schlüssel in Umgebungsvariablen oder einem Geheimnis-Manager. Niemals in Git committen, niemals im Chat teilen. Schlüssel, die in öffentlichen Repositories landen, werden regelmäßig innerhalb von Minuten abgegriffen.
• Ein Schlüssel pro Umgebung. Teilen Sie keinen ck_live_...-Schlüssel zwischen Staging und Produktion. Die Rotation des einen soll den anderen nicht beeinträchtigen.
• Verwenden Sie eingeschränkte Schlüssel. Ein Schlüssel nur zum Lesen für das Monitoring und ein Schlüssel zum Schreiben für den Onboarding-Dienst sind sicherer als ein allmächtiger Schlüssel überall.
• Binden Sie Schlüssel an Ihre Server. Tragen Sie für Schlüssel, die nur von festen Adressen aus verwendet werden, die IP-Zulassungsliste ein.
• Rotieren Sie vierteljährlich. Verwenden Sie Rotieren (siehe unten). Der alte Schlüssel funktioniert während der von Ihnen gewählten Überlappung weiter, sodass Sie den neuen ohne Ausfallzeit einsetzen können. Das Audit-Protokoll erfasst den Wechsel.
• Achten Sie auf unbefugte Nutzung. Die Schlüsselliste zeigt, wann und von welcher Adresse jeder Schlüssel zuletzt verwendet wurde. Das Audit-Protokoll erfasst das Erstellen, Bearbeiten, Rotieren und Widerrufen von Schlüsseln. Prüfen Sie jede Adresse, die Sie nicht kennen.

Einen Schlüssel rotieren

Entwickler → API-Schlüssel → Rotieren erstellt einen Ersatz mit derselben Bezeichnung, denselben Berechtigungen, Einschränkungen, derselben IP-Zulassungsliste und demselben Ablaufdatum. Der neue Schlüssel wird einmal angezeigt.

• Überlappung (0–168 Stunden, Standard 24). Der alte Schlüssel funktioniert so lange weiter und liefert danach 401 api_key_rotated. Mit 0 widerrufen Sie den alten Schlüssel sofort.
• Die Liste markiert den alten Schlüssel als „Rotiert — alter Schlüssel funktioniert bis …“ und den neuen als „Ersetzt einen rotierten Schlüssel“. Ein bereits rotierter Schlüssel kann nicht erneut rotiert werden. Rotieren Sie stattdessen seinen Ersatz.
• Sie können den alten Schlüssel während der Überlappung auch bearbeiten oder widerrufen, falls Sie ihn früher abschalten möchten.

Einen Schlüssel widerrufen

Wenn ein Schlüssel kompromittiert, geleakt oder nicht mehr benötigt ist:

• Entwickler → API-Schlüssel → Menü mit drei Punkten → Widerrufen.
• Wirkt sofort. Jede laufende Anfrage mit dem Schlüssel erhält beim nächsten Aufruf 401.
• Nicht rückgängig zu machen. Es gibt keine Schaltfläche „Widerruf aufheben“. Stellen Sie einen neuen Schlüssel aus, falls Sie es bereuen.

Der Widerruf wird im Audit-Protokoll zusammen mit dem Benutzer erfasst, der ihn durchgeführt hat.

Live oder Test

Jeder Schlüssel ist entweder:

• Test (ck_test_...) — für Entwicklung und CI gedacht.
• Live (ck_live_...) — für die Produktion gedacht.

Die Umgebung kennzeichnet die Nutzung: Jede Antwort enthält X-Certivant-Environment: test oder live. Das Dashboard zeigt das Badge neben dem Schlüssel. So können Sie in Ihren Protokollen Testverkehr von Produktionsverkehr unterscheiden.

Fehlerbehebung

401 Unauthorized

Der Eintrag error.reason im Antworttext verrät den Grund:

403 Forbidden

error.reason:

429 Too Many Requests

Sie sind an der Ratenbegrenzung. Prüfen Sie den Header Retry-After (Sekunden) und warten Sie entsprechend. Bei dauerhaft hohem Volumen fragen Sie ein höheres Limit an.

„Ich habe den Schlüssel verloren“

Schlüssel werden nur einmal angezeigt. Eine Wiederherstellung ist nicht möglich. Widerrufen Sie den alten Schlüssel und stellen Sie einen neuen aus. Ihr Team muss den neuen Wert überall dort eintragen, wo der alte bereitgestellt war.

Verwandte Themen

• Webhooks — in Kombination mit der API für die vollständige Integration.
• KYC-Liste & Details — die Ansicht im Dashboard für über die API angelegte Anfragen.
• Audit-Protokoll — jeder API-Aufruf erscheint hier.