Entwickler
Zwei Endpunkte bis zum Ergebnis
Prüfung starten, Link zeigen, Ergebnis lesen. Signierte Anfragen, verschlüsselte Antworten, Vertrauenslisten und Widerruf erledigt der Dienst.
curl -X POST "$VERYSAFE_HOST/v1/verifications" \
-H "Authorization: Bearer $VERYSAFE_KEY" \
-H "Content-Type: application/json" \
-d '{ "credentialType": "eu_pid",
"claims": ["age_equal_or_over.18"],
"flow": "cross_device" }'const res = await fetch(process.env.VERYSAFE_HOST + "/v1/verifications", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.VERYSAFE_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
credentialType: "eu_pid",
claims: ["age_equal_or_over.18"],
flow: "cross_device",
}),
});
const check = await res.json();
// show check.authorizationRequestUri as a QR codeimport os, requests
check = requests.post(
os.environ["VERYSAFE_HOST"] + "/v1/verifications",
headers={"Authorization": "Bearer " + os.environ["VERYSAFE_KEY"]},
json={
"credentialType": "eu_pid",
"claims": ["age_equal_or_over.18"],
"flow": "cross_device",
},
).json()
# show check["authorizationRequestUri"] as a QR code
201 Created
{ "id": "0f6c1a2e…",
"status": "pending",
"flow": "cross_device",
"credentialType": "eu_pid",
"requestedClaims": ["age_equal_or_over.18"],
"authorizationRequestUri": "openid4vp://?client_id=…",
"pollUrl": "/v1/verifications/0f6c1a2e…" }
Dann, sobald die Person geantwortet hat · GET /v1/verifications/{id} · 200 OK
{ "id": "0f6c1a2e…",
"status": "verified",
"result": {
"claims": { "age_equal_or_over": { "18": true } } } }
Schnellstart
Schlüssel holen
Sandbox-Schlüssel sind kostenlos und decken die ganze API ab.
Prüfung starten
Senden Sie per POST die benötigten Angaben und den Ablauf (flow). Sie erhalten einen Link, einen QR-Code oder eine Browser-Anfrage.
Ergebnis lesen
Fragen Sie die Prüfung ab oder nehmen Sie den signierten Webhook. Verifiziert, mit dem Geteilten – oder ein Grund, warum nicht.
So läuft eine Prüfung ab
Wer mit wem spricht, von der Anfrage bis zum Ergebnis.
- Ihre Anwendung → VerySafePrüfung starten
POST /v1/verifications - VerySafe → Ihre AnwendungEin Link, ein QR-Code oder eine Browser-Anfrage
201 Created - Ihre Anwendung → Wallet der PersonDie Person öffnet sie in ihrer Wallet
- Wallet der Person → VerySafeHolt die signierte Anfrage
request.jwt - Wallet der Person → VerySafeSendet die verschlüsselte Antwort, wenn die Person zustimmt
- VerySafePrüft den Aussteller gegen die EU-Vertrauenslisten (in der Sandbox die Testlisten der EU), Widerruf, Ablauf und die Bindung an diese Anfrage
- VerySafe → Ihre AnwendungDas Ergebnis, mit dem, was die Person geteilt hat
GET /v1/verifications/{id} · Webhook
Auf demselben Handy schickt die Wallet die Person danach zu Ihrer returnUrl, und Ihr Server gibt das Ergebnis mit POST /v1/verifications/{id}/exchange frei.
Drei Wege, eine API
Ein Endpunkt, ein Parameter: flow. Ihre Anwendung wählt bei jeder Prüfung.
flow: "cross_device"QR-Code am Computer
Zeigen Sie
authorizationRequestUrials QR-Code. Die Person scannt ihn mit der Wallet auf ihrem Handy; Sie fragen die Prüfung ab oder nehmen den Webhook.flow: "same_device"Ein Link auf demselben Handy
Öffnen Sie
authorizationRequestUrials Link und senden Sie einereturnUrlmit. Die Wallet bringt die Person mit einemresponse_codedorthin zurück, und Ihr Server tauscht ihn gegen das Ergebnis.flow: "dc_api"Der Browser fragt direkt
Ihre Seite übergibt
dcApiRequestsan die Digital Credentials API des Browsers und leitet die Antwort andcApiResponseUrlweiter, in Chrome auf Android und Safari auf dem iPhone.@verysafe/verifyerledigt das für Sie und weicht auf Link oder QR-Code aus.
Die API im Überblick
Acht Endpunkte, die Ihre Anwendung aufruft. Die Seite der Wallet läuft über eigene Endpunkte.
- GET
/v1/credential-typesWas jeder Nachweis offenlegen kann - POST
/v1/verificationsPrüfung starten und Wallet-Link erhalten - GET
/v1/verifications/{id}Status und Ergebnis: pending, awaiting_return, verified, failed oder expired - POST
/v1/verifications/{id}/exchangeSelbes Handy: Ergebnis mit dem Antwortcode der Person freigeben - GET
/v1/verdictsIhr Ergebnisverlauf für Audits, ohne personenbezogene Werte - GET
/v1/metricsZähler und Zustand jeder EU-Vertrauensliste - GET
/v1/webhook-deliveriesSignierte Webhook-Zustellungen, und eine erneut senden - POST
/v1/mcpDieselben Prüfungen als Tools für KI-Agenten
Jede Ablehnung nennt einen Grund
Jede Ablehnung sagt, warum, in Worten, die Sie anzeigen oder protokollieren können.
- Aussteller steht nicht auf der EU-Vertrauensliste
- Aussteller zurückgezogen oder ausgesetzt
- Nachweis vom Aussteller widerrufen
- Zertifikat des Ausstellers widerrufen
- Nachweis abgelaufen
- Nachweis nicht an diese Anfrage gebunden
- Widerrufsstatus nicht prüfbar, daher lautet die Antwort Nein
Für KI-Agenten
Drei Tools: list_supported_credential_types, verify_credential und check_verification. Der Agent erhält das Ergebnis und die Namen der nachgewiesenen Angaben, nie deren Werte.
POST /v1/mcp
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "check_verification",
"arguments": { "session_id": "0f6c1a2e…" } } }
→ { "session_id": "0f6c1a2e…",
"verdict": "verified",
"credential_type": "eu_pid",
"disclosed_claim_names": ["age_equal_or_over.18"] }Signierte Webhooks
Statt abzufragen: Als Partner geben Sie uns für jeden Kunden eine URL, und jedes Ergebnis wird dorthin gesendet. Ein Ergebnis auf demselben Handy erst nach dem Austausch. Mit einem Sandbox-Schlüssel fragen Sie die Prüfung ab.
Jede Zustellung trägt einen Signature-Header: eine abgetrennte JWS, ES256, über den exakten Body. Der Schlüssel liegt unter /.well-known/jwks.json.
Antworten Sie mit 2xx, gilt das Ergebnis als zugestellt, und wir löschen seine Angaben. Sonst wird es sechsmal über etwa neun Stunden wiederholt und lässt sich 30 Tage lang erneut senden.
Gehostet oder auf Ihren eigenen Servern
Derselbe Dienst läuft als signiertes Container-Image, öffentlich auf ghcr.io mit seiner Software-Stückliste (SBOM). Lizenz, Helm-Chart und Installationsanleitung bekommen Sie von uns.
Sandbox-Schlüssel anfordern
Testumgebung und Testnachweise. Keine Kreditkarte nötig. Ein Mensch antwortet mit Ihrem Schlüssel.
Ressourcen
- API-Referenz zum AusprobierenJeder Endpunkt, auf der Sandbox, in Ihrem Browser. (öffnet in einem neuen Tab)
- Das OpenAPI-DokumentDieselbe Referenz als eine Datei, für Ihre Werkzeuge. (öffnet in einem neuen Tab)
- Die Browser-Bibliothek, @verysafe/verifyZuerst die Abfrage im Browser, dann ein Link auf dem Handy, dann ein QR-Code. Auf npm. (öffnet in einem neuen Tab)
- AblehnungsgründeJeder Grund, aus dem eine Prüfung Nein sagen kann.
- MCP für KI-AgentenDie drei Tools und was sie zurückgeben.
