Wissen, wer Ihr Kunde ist – ohne seinen Ausweis aufzubewahren

1. Einen Client erhalten

Wir registrieren Ihren Client — eine Client-ID und ein Secret, das nur einmal angezeigt wird —, einen Plan (Stufe, Claims und der Zweck, den die Person liest) und Ihre Redirect-URIs: eine https-Seite, das eigene Schema Ihrer App (yourapp://verify) oder beides. Jeder Client erhält vor dem Livegang eine eigene Testumgebung.

2. Die Anfrage aus Ihrem Backend senden

Nie aus einem Browser oder einer App: Das Secret bleibt auf Ihrem Server. Sie erhalten einen Einmal-Link, zehn Minuten gültig; sobald er geöffnet ist, hat die Person eine Stunde Zeit für den Abschluss.

POST https://api.ism.ec/verify/v1/par
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "plan_id":       "bn_…",
  "redirect_uri":  "yourapp://verify",
  "state":         "<zufällig, in Ihrer Sitzung gespeichert>"
}

→ { "req": "…", "verify_url": "https://id.ism.ec/go?req=…", "expires_at": "…" }

3. Die Person prüft

Öffnen Sie den Link auf ihrem Telefon, zeigen Sie ihn am Desktop als QR-Code an oder senden Sie ihn auf dem Weg, auf dem Sie Ihren Kunden ohnehin erreichen. Der Link enthält nur eine undurchsichtige Referenz — keinen Client, keinen Umfang, keine personenbezogenen Daten.

4. Zurück zu Ihnen

Wenn die Person fertig ist, öffnet ID Protekt Ihre redirect_uri mit ?code=…&state=…. Prüfen Sie, dass state der Wert ist, den Sie gespeichert haben.

5. Die Antwort abholen

Lösen Sie den Code sofort ein: Er ist einmalig verwendbar, 120 Sekunden gültig, und nur der Client, für den er ausgestellt wurde, kann ihn einlösen. Die Zugangsdaten stehen im Body oder werden per HTTP Basic übergeben.

POST https://api.ism.ec/verify/v1/token
{ "client_id": "cl_…", "client_secret": "…", "code": "<aus dem Redirect>" }

→ {
    "claims":             { "subject_is": true },
    "assurance":          "L4",
    "verified_by":        "device",
    "device_attestation": "…",
    "verified_at":        "…",
    "consent_receipt_id": "…",
    "state":              "…"
  }

Nicht zurückgekehrt? Sie erhalten die Antwort trotzdem

Registrieren Sie einen Webhook, und Ihr Backend erfährt jedes Ergebnis — abgeschlossen, abgelehnt oder fehlgeschlagen —, auch wenn die Person in der App ID Protekt abschließt und nie zurückkehrt oder am Desktop begonnen hat. Jedes Ereignis ist mit Ihrem eigenen whsec_-Secret signiert (ISM-Signature, HMAC-SHA256), trägt die Referenz der Anfrage und keine personenbezogenen Daten und wird etwa einen Tag lang erneut zugestellt. Rufen Sie das Ergebnis dann innerhalb von 24 Stunden über die Referenz ab:

POST https://api.ism.ec/verify/v1/token
{
  "client_id":     "cl_…",
  "client_secret": "…",
  "grant_type":    "request",
  "req":           "<aus dem Webhook>"
}

Die Antwort wird genau einmal herausgegeben, über den Code oder über die Referenz — je nachdem, was zuerst kommt.

Lesen Sie den Claim, nicht den Status. Eine abgeschlossene Prüfung ist keine bestandene: subject_is: false ist eine Ablehnung, und ein fehlender Claim wurde nicht bewiesen. Halten Sie die Sitzung der Person offen, damit sie es einfach erneut versuchen kann, falls sie nicht zurückkehrt.