
Ein moderner Verifizierungs-Stack von innen
Wie Dokumenten-, Biometrie- und Signalprüfungen in einer produktiven Prüfpipeline zusammenspielen.
5 Min. · Oktober 2026
Weiterlesen: Ein moderner Verifizierungs-Stack von innenFehlt ein Land oder eine eigene Prüfung? Sagen Sie uns, was Sie brauchen.15-Minuten-Gespräch buchen
Wie Sie Identitäts- oder Altersprüfung in eine Web-App einbinden, von der ersten Sandbox-Session bis zu Webhooks und signierten Ergebnissen, und welche Fehler dabei leicht passieren.
Von secuveri teamVeröffentlicht

Der Code für eine Identitätsprüfung in einer Web-App ist überschaubar. Ihr Server erstellt eine Session, die Person durchläuft einen gehosteten Ablauf, und Ihr Server liest das Ergebnis. Die meisten Integrationsfehler entstehen bei den Entscheidungen rund um diesen Code: welchem Signal Sie vertrauen, was bei einer wiederholten Anfrage passiert und was die App tut, solange ein Fall auf eine manuelle Prüfung wartet.
Diese Anleitung geht die Integration in der Reihenfolge durch, in der Sie sie bauen würden, mit der API von secuveri und den Open-Source-Beispiel-Apps. Wenn Sie zuerst das fertige Ergebnis sehen möchten, probieren Sie die Bank-Demo oder die 18+-Shop-Demo. Beide laufen in der Sandbox.
Es gibt drei Teile:
Der Browser ist nur an Schritt 2 beteiligt. Das ist Absicht und prägt den Rest der Integration.
Erstellen Sie im Dashboard unter Settings, API keys einen Sandbox-Schlüssel. Sandbox-Schlüssel beginnen mit sk_test_, Produktionsschlüssel mit sk_live_. Beide gehören ausschliesslich auf Ihren Server.
Erstellen und veröffentlichen Sie danach einen Sandbox-Workflow mit den Prüfungen, die Sie brauchen. Wenn Sie den Ablauf in Ihre Seite einbetten, tragen Sie Ihren lokalen Origin, zum Beispiel http://localhost:3030, unter Settings, Branding in die Liste der Websites ein, die den Ablauf einbetten dürfen.
Die Sandbox führt die echten Prüfungen aus. Sie können sich also während der Entwicklung mit Ihrem eigenen Dokument verifizieren. Zusätzlich gibt es kostenlose Szenarien, die eine Session sofort mit dem gewählten Ergebnis abschliessen, angenommen, abgelehnt oder zur Prüfung, ganz ohne Dokument. Damit testen Sie Ihre Codepfade. Die Pfade für Ablehnung und manuelle Prüfung werden Sie viel öfter durchspielen wollen, als irgendjemand Lust auf ein Selfie hat.
Eine Session ist ein einziger API-Aufruf: POST /v1/sessions mit Ihrem API-Schlüssel im Header x-api-key, der Workflow-ID und Ihrer eigenen Referenz in vendor_data. Die Antwort enthält eine Verifizierungs-ID und den Link zum Ablauf. Mit dem Node.js-Paket @secuveri/node heisst derselbe Aufruf createSession.
Zwei Details ersparen Ihnen später Ärger:
Geben Sie dem Browser nur den Session-Link oder das Token zurück. Der API-Schlüssel verlässt Ihren Server nie.
Sie können die Person auf den Link weiterleiten, ihn als QR-Code anzeigen oder ihn von secuveri per E-Mail oder SMS verschicken lassen. Damit die Leute in Ihrer App bleiben, nutzen Sie das Browser-Paket @secuveri/web und rufen Secuveri.start mit der Session-URL auf. Es öffnet den Ablauf in einem Modal oder einem eingebetteten Frame und meldet den Fortschritt über Callbacks wie onComplete, onCancel und onError.
onComplete bedeutet, dass die Person am Ende des Ablaufs angekommen ist. Es bedeutet nicht, dass sie bestanden hat, und jede Person mit Zugriff auf die Entwicklerkonsole kann es aufrufen. Behandeln Sie es als Hinweis, Ihren eigenen Server nach dem Ergebnis zu fragen, nie als das Ergebnis selbst.
Das Shop-Beispiel zeigt das gut. Der Checkout gibt eine Bestellung erst auf, wenn der Server ein angenommenes Ergebnis für genau diese Bestellung hat. Wer onComplete von Hand aufruft, ändert nichts, denn der Server findet weiterhin kein angenommenes Ergebnis.
Wenn eine Prüfung abgeschlossen oder manuell geprüft wurde, sendet secuveri einen Webhook an den Endpunkt, den Sie unter Settings, Webhooks hinterlegt haben. Das Webhook-Receiver-Beispiel erledigt das in einer einzigen Datei. Es hält sich an diese Regeln:
Der Webhook-Endpunkt muss eine öffentliche https-URL sein. Für die lokale Entwicklung nutzen Sie einen Tunnel, oder Sie verlassen sich bis zum Deployment auf den Browser-Callback mit anschliessender Ergebnisprüfung auf dem Server.
Rufen Sie das Ergebnis mit der Verifizierungs-ID ab (getResult in @secuveri/node). Es kommt als signiertes Ergebnis: ein ES256-JWS, das Sie mit den öffentlichen Schlüsseln unter /.well-known/jwks.json prüfen. Es enthält keine Personendaten. Sie können es also als Nachweis der Entscheidung aufbewahren, ohne Dokumentbilder oder Geburtsdaten zu speichern.
Bevor Sie darauf reagieren, prüfen Sie:
Führen Sie dieselbe Abschlusslogik im Browser-Pfad und im Webhook-Pfad aus, und sorgen Sie dafür, dass sie zweimal laufen darf. Was zuerst ankommt, schliesst den Fall ab, das Zweite findet nichts mehr zu tun.
Stellen Sie vor dem Livegang sicher, dass Ihre App vernünftig reagiert, wenn:
Die Sandbox-Szenarien decken die Ergebnisse ab. Der Rest ist gewöhnliches Testen Ihres eigenen Codes.
Der Wechsel in die Produktion ist eine Konfigurationsänderung: ein sk_live_-Schlüssel, ein veröffentlichter Produktions-Workflow, Ihr Produktions-Origin in der Einbettungsliste und ein Webhook-Endpunkt mit seinem Signaturgeheimnis. Der Code bleibt gleich.
Die vollständige API-Referenz, inklusive Fehlercodes und AML-Screening, finden Sie nach der Anmeldung im Dashboard unter app.secuveri.com/docs. Einen Überblick über die API bietet die Entwicklerseite.
Dieser Beitrag dient der allgemeinen Information und ist keine Rechts- oder Compliance-Beratung. Ihre Pflichten hängen von Branche, Bewilligung und Märkten ab.
Gestalten Sie eine Identitätsprüfung, die zu Ihrem Geschäft passt.

Wie Dokumenten-, Biometrie- und Signalprüfungen in einer produktiven Prüfpipeline zusammenspielen.
5 Min. · Oktober 2026
Weiterlesen: Ein moderner Verifizierungs-Stack von innen
Was auf dem Chip eines Passes oder einer Identitätskarte gespeichert ist, wie ein Smartphone ihn ausliest und prüft und warum er mehr verrät als jedes Foto des Dokuments.
6 Min. · November 2026
Weiterlesen: So funktioniert die NFC-Chipprüfung bei Pass und IdentitätskarteSagen Sie uns, was Sie prüfen möchten. Wir zeigen Ihnen, wie secuveri in Ihren Ablauf passt.