VerySafe Kontakt

Entwickler

Zwei Endpunkte bis zum Ergebnis

Prüfung starten, Link zeigen, Ergebnis lesen. Signierte Anfragen, verschlüsselte Antworten, Vertrauenslisten und Widerruf erledigt der Dienst.

Sprache des Codebeispiels
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 code
import 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

  1. Schlüssel holen

    Sandbox-Schlüssel sind kostenlos und decken die ganze API ab.

  2. 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.

  3. 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.

  1. Ihre Anwendung → VerySafePrüfung starten POST /v1/verifications
  2. VerySafe → Ihre AnwendungEin Link, ein QR-Code oder eine Browser-Anfrage 201 Created
  3. Ihre Anwendung → Wallet der PersonDie Person öffnet sie in ihrer Wallet
  4. Wallet der Person → VerySafeHolt die signierte Anfrage request.jwt
  5. Wallet der Person → VerySafeSendet die verschlüsselte Antwort, wenn die Person zustimmt
  6. VerySafePrüft den Aussteller gegen die EU-Vertrauenslisten (in der Sandbox die Testlisten der EU), Widerruf, Ablauf und die Bindung an diese Anfrage
  7. 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 authorizationRequestUri als 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 authorizationRequestUri als Link und senden Sie eine returnUrl mit. Die Wallet bringt die Person mit einem response_code dorthin zurück, und Ihr Server tauscht ihn gegen das Ergebnis.

  • flow: "dc_api"

    Der Browser fragt direkt

    Ihre Seite übergibt dcApiRequests an die Digital Credentials API des Browsers und leitet die Antwort an dcApiResponseUrl weiter, in Chrome auf Android und Safari auf dem iPhone. @verysafe/verify erledigt 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.

tools/call · check_verification
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.