Fehlt ein Land oder eine eigene Prüfung? Sagen Sie uns, was Sie brauchen.15-Minuten-Gespräch buchen

Identitätsprüfung in eine Web-App einbauen: Anleitung mit Sandbox

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.

7 Min. LesezeitNovember 2026

Von secuveri teamVeröffentlicht

Eine Entwicklerin bindet die Identitätsprüfung in eine Webanwendung ein

Kurz gesagt

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.

Wie die Teile zusammenspielen

Es gibt drei Teile:

  1. Ihr Backend erstellt eine Session für eine Person und einen Workflow. Ein Workflow ist die Zusammenstellung der Prüfungen, die Sie konfiguriert haben, zum Beispiel Ausweisdokument, Lebenderkennung und Gesichtsabgleich oder ein Mindestalter.
  2. Die Person durchläuft den Ablauf auf einer gehosteten Seite oder in einem in Ihre App eingebetteten Frame. Am Computer zeigt der Ablauf einen QR-Code, damit sie auf dem Smartphone weitermachen kann, wo Kamera und NFC sind.
  3. Ihr Backend erfährt das Ergebnis, über einen signierten Webhook und ein signiertes Ergebnis, das es bei der API abruft.

Der Browser ist nur an Schritt 2 beteiligt. Das ist Absicht und prägt den Rest der Integration.

Mit der Sandbox beginnen

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.

Die Session auf Ihrem Server erstellen

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:

  • Tragen Sie Ihre eigene ID in vendor_data ein. Nehmen Sie die Konto- oder Bestell-ID, zu der die Prüfung gehört. Sie prüfen sie wieder, wenn das Ergebnis zurückkommt.
  • Senden Sie einen Idempotency-Key. Leiten Sie ihn aus derselben ID ab, zum Beispiel aus der Bestell-ID. Wird Ihre Anfrage nach einem Timeout wiederholt, erhalten Sie dieselbe Session zurück statt einer zweiten.

Geben Sie dem Browser nur den Session-Link oder das Token zurück. Der API-Schlüssel verlässt Ihren Server nie.

Den Ablauf öffnen

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.

Dem Browser-Callback nicht vertrauen

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.

Den Webhook richtig behandeln

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:

  • Die Signatur über den Rohdaten prüfen. Der Header secuveri-signature ist ein HMAC-SHA256 über genau die empfangenen Bytes. Parst Ihr Framework das JSON vorher und serialisiert es neu, passt die Signatur nicht mehr.
  • Schnell antworten. Geben Sie innerhalb von 10 Sekunden einen 2xx-Status zurück und erledigen Sie langsame Arbeit danach. Alles andere wird wiederholt, 7-mal über etwa 21 Stunden.
  • Duplikate über die Event-ID erkennen. Sie bleibt bei Wiederholungen gleich. Speichern Sie also die IDs, die Sie verarbeitet haben.
  • Den Webhook als Auslöser nutzen. Stützen Sie die Entscheidung auf das signierte Ergebnis, nicht allein auf den Inhalt des Webhooks.

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.

Das signierte Ergebnis lesen und prüfen

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:

  • Es gehört zu diesem Fall. vendor_data stimmt mit Ihrer Konto- oder Bestell-ID überein, und die Workflow-ID ist die erwartete. Sonst könnte ein gültiges Ergebnis aus einem anderen, einfacheren Workflow gegen Ihren Checkout wiederverwendet werden.
  • Den Status. COMPLETE mit dem Verdict APPROVED lässt die Person durch. REVIEW_REQUIRED heisst, dass jemand in Ihrem Team noch entscheiden muss. Lassen Sie den Fall dann offen, statt ihn abzulehnen. Alles andere ist kein Bestehen.
  • Einzelne Prüfungen, wo es darauf ankommt. Ein Shop mit Altersbeschränkung prüft zum Beispiel zusätzlich, ob die Alterskontrolle im Ergebnis sein eigenes Mindestalter erfüllt.

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.

Testen, was schiefgehen kann

Stellen Sie vor dem Livegang sicher, dass Ihre App vernünftig reagiert, wenn:

  • die Person den Ablauf mittendrin schliesst,
  • das Ergebnis eine Ablehnung ist oder in die manuelle Prüfung geht und einen Tag später angenommen wird,
  • der Webhook vor dem Browser-Callback eintrifft oder umgekehrt,
  • derselbe Webhook zweimal eintrifft,
  • Ihre Session-Anfrage in einen Timeout läuft und wiederholt wird,
  • jemand Ihren Abschluss-Endpunkt für eine Bestellung ohne Prüfung aufruft.

Die Sandbox-Szenarien decken die Ergebnisse ab. Der Rest ist gewöhnliches Testen Ihres eigenen Codes.

Livegang

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.

secuveri

Gestalten Sie eine Identitätsprüfung, die zu Ihrem Geschäft passt.

Weiterlesen

Kontakt

Sprechen Sie mit uns

Sagen Sie uns, was Sie prüfen möchten. Wir zeigen Ihnen, wie secuveri in Ihren Ablauf passt.

Wir antworten innerhalb eines Arbeitstages und verwenden Ihre Angaben nur für Ihre Anfrage. Siehe unsere Datenschutzerklärung.