VerySafe Talk to us

Developers

Two endpoints to a verdict

Start a check, show the link, read the verdict. Signed requests, encrypted responses, trust lists and revocation all happen in the service.

Code sample language
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…" }

Then, once the person has answered · GET /v1/verifications/{id} · 200 OK

{ "id": "0f6c1a2e…",
  "status": "verified",
  "result": {
    "claims": { "age_equal_or_over": { "18": true } } } }

Quickstart

  1. Get a key

    Sandbox keys are free and cover the full API.

  2. Start a check

    POST the claims you need and the flow. You get a link, a QR code or a browser request.

  3. Read the verdict

    Poll the check, or take the signed webhook. Verified with what was shared, or a reason why not.

How a check runs

Who talks to whom, from the request to the verdict.

  1. Your application → VerySafeStart a check POST /v1/verifications
  2. VerySafe → Your applicationA link, a QR code or a browser request 201 Created
  3. Your application → The person's walletThe person opens it in their wallet
  4. The person's wallet → VerySafeFetches the signed request request.jwt
  5. The person's wallet → VerySafeSends the encrypted answer, once the person agrees
  6. VerySafeChecks the issuer against the EU trusted lists (the EU's test lists on the sandbox), revocation, expiry and the binding to this request
  7. VerySafe → Your applicationThe verdict, with what the person shared GET /v1/verifications/{id} · webhook

On the same phone, the wallet then sends the person to your returnUrl, and your server releases the result with POST /v1/verifications/{id}/exchange.

Three ways in, one API

One endpoint, one parameter: flow. Your application chooses for each check.

  • flow: "cross_device"

    QR code on a computer

    Show authorizationRequestUri as a QR code. The person scans it with the wallet on their phone; you poll the check or take the webhook.

  • flow: "same_device"

    A link on the same phone

    Open authorizationRequestUri as a link and send a returnUrl. The wallet brings the person back to it with a response_code, which your server exchanges for the result.

  • flow: "dc_api"

    The browser asks directly

    Your page hands dcApiRequests to the browser's Digital Credentials API and relays the answer to dcApiResponseUrl, in Chrome on Android and Safari on iPhone. @verysafe/verify does this for you, and falls back to a link or a QR code.

The API at a glance

Eight endpoints your application calls. The wallet's side of the exchange runs on endpoints of its own.

  • GET/v1/credential-typesWhat each credential can disclose
  • POST/v1/verificationsStart a check and get a wallet link
  • GET/v1/verifications/{id}Status and result: pending, awaiting_return, verified, failed or expired
  • POST/v1/verifications/{id}/exchangeSame phone: release the result with the person's response code
  • GET/v1/verdictsYour verdict history for audits, without personal values
  • GET/v1/metricsCounters and the health of each EU trusted list
  • GET/v1/webhook-deliveriesSigned webhook deliveries, and replaying one
  • POST/v1/mcpThe same checks as tools for AI agents

Every refusal has a reason

Every refusal says why, in words you can show or log.

  • Issuer is not on the EU trusted list
  • Issuer withdrawn or suspended
  • Credential revoked by its issuer
  • Issuer certificate revoked
  • Credential expired
  • Proof not bound to this request
  • Revocation status could not be checked, so the answer is no

For AI agents

Three tools: list_supported_credential_types, verify_credential and check_verification. The agent gets the verdict and the names of the facts proven, never their values.

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"] }

Webhooks, signed

Instead of polling, a partner gives us a URL for each client and every result is pushed to it. A same-phone result is pushed after its exchange. With a sandbox key, poll the check.

Each delivery carries a Signature header: a detached JWS, ES256, over the exact body. The key is at /.well-known/jwks.json.

Answer with a 2xx and the result counts as delivered, and we delete its claims. Otherwise it is retried six times over about nine hours, and can be replayed for 30 days.

Hosted, or on your own servers

The same service runs as a signed container image, public on ghcr.io with its software bill of materials. The licence, the Helm chart and the install guide come from us.