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.
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…" }
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
Get a key
Sandbox keys are free and cover the full API.
Start a check
POST the claims you need and the flow. You get a link, a QR code or a browser request.
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.
- Your application → VerySafeStart a check
POST /v1/verifications - VerySafe → Your applicationA link, a QR code or a browser request
201 Created - Your application → The person's walletThe person opens it in their wallet
- The person's wallet → VerySafeFetches the signed request
request.jwt - The person's wallet → VerySafeSends the encrypted answer, once the person agrees
- VerySafeChecks the issuer against the EU trusted lists (the EU's test lists on the sandbox), revocation, expiry and the binding to this request
- 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
authorizationRequestUrias 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
authorizationRequestUrias a link and send areturnUrl. The wallet brings the person back to it with aresponse_code, which your server exchanges for the result.flow: "dc_api"The browser asks directly
Your page hands
dcApiRequeststo the browser's Digital Credentials API and relays the answer todcApiResponseUrl, in Chrome on Android and Safari on iPhone.@verysafe/verifydoes 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.
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.
Get a sandbox key
Test environment and test credentials. No card needed. A person replies with your key.
Resources
- API reference, to tryEvery endpoint, on the sandbox, in your browser. (opens in a new tab)
- The OpenAPI documentThe same reference as one file, for your tools. (opens in a new tab)
- The browser library, @verysafe/verifyThe browser prompt first, then a link on a phone, then a QR code. On npm. (opens in a new tab)
- Refusal reasonsEvery reason a check can answer no.
- MCP for AI agentsThe three tools, and what they return.
