{"openapi":"3.1.0","info":{"title":"VerySafe EUDI Verifier","version":"1.2.0-dev","description":"Verifies a person's EU digital identity credentials (EU personal ID, mobile driving licence) through their wallet, over OpenID4VP. Generated from src/api/description.ts by `npm run docs:openapi`."},"servers":[{"url":"{baseUrl}","variables":{"baseUrl":{"default":"https://verify.verysafe.id","description":"VerySafe's service, or your own `PUBLIC_BASE_URL`."}}}],"tags":[{"name":"verifications","description":"Ask a person's wallet for a credential, and read the verdict."},{"name":"operations","description":"Verdict log, metrics and usage."},{"name":"agents","description":"For AI agents: verdicts only, never claim values."},{"name":"service","description":"Health, the public conformance record, and this API's description and reference."},{"name":"wallet","description":"Called by the person's wallet, not by your application (OpenID4VP)."}],"paths":{"/v1/credential-types":{"get":{"operationId":"listCredentialTypes","tags":["verifications"],"summary":"What can be asked for","security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"The credential types, and the claims each can disclose.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialTypeList"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications":{"post":{"operationId":"startVerification","tags":["verifications"],"summary":"Start a verification","description":"Returns the link the person's wallet opens. The body is optional: without one, it asks for an EU personal ID (`eu_pid`) and its default claims, across devices. Say how the person presents with `flow`. On VerySafe's hosted service `flow` is required: a start without it is refused with a 400 that names it (since 2026-10-13). A self-hosted installation defaults to `cross_device` until a release of its own says otherwise.","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key with the same request, within an hour, answers with the same verification. Keys are your API key's own.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartVerificationRequest"}}}},"responses":{"201":{"description":"Started. Show `authorizationRequestUri` to the person, or with `dc_api` pass `dcApiRequests` to the browser, then poll `pollUrl`.","headers":{"Idempotent-Replayed":{"description":"`true` when this is the answer an earlier request with the same Idempotency-Key got.","schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationStarted"}}}},"400":{"description":"An unknown credential type or claim, a reference or metadata that is refused, a malformed Idempotency-Key, no `flow` on the hosted service, or a `flow` or `returnUrl` that is refused: an unknown flow, `same_device` without `returnUrl`, `returnUrl` without it, or a `returnUrl` that is not https on an allowed origin; `dc_api` where the service allows no page to ask through the browser prompt; a `linkScheme` or `requestUriMethod` that is not one described, or one sent with `dc_api`; or, where your key belongs to a Service with registered uses, a request that no one of them covers (I4), an `intendedUse` that is none of them or does not cover it, or a use whose registration certificate has expired, is revoked or suspended, or is not bound to the access certificate the request is signed with (I3); or a Service whose own access certificate no longer holds (I2): expired, revoked by its CA, or not checkable for revocation (I9).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your key's customer, or its Service, is stopped by the operator: its registration is suspended or cancelled, its agreement has ended, or its certificates are being replaced (I9). Nothing starts until it is resumed; verifications already started finish, and their results stay readable. Or, where the service requires it, your key belongs to no customer: every request is made in a customer's name, so the operator attaches the key first (decision 0103).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used with a different request, or its first request has not finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed to start the verification, for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A production installation whose licence does not allow new verifications: none, expired past its grace period, or one for another deployment role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}":{"get":{"operationId":"getVerification","tags":["verifications"],"summary":"Read a verification's outcome","description":"Only the API key that started a verification may read it, or, where that key is a customer's, another of that customer's keys. It is deleted after its retention period. A `same_device` verification's result is not released here while it is `awaiting_return`: exchange its response code.\n\nOn VerySafe's hosted service (since 2026-10-13; decisions 0051 and 0083) a result's claims are delivered once: the first read after the verdict, or the exchange, gets them and deletes them, and a later read gets the verdict with `deliveredAt` and no claims; the verdict log and the metrics feed carry no issuer, claim names or reference. Read a result once and keep what you need. A self-hosted installation keeps its results until its retention.\n\nPoll it every 2 seconds while it is `pending`, and no faster. Polls are counted per API key in a budget of their own (`POLL_RATE_LIMIT_PER_MINUTE`), apart from starts and every other call, so polling never stops a key from starting verifications. Over it, the answer is `429`: wait the `Retry-After` seconds it gives before polling again.","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Its status, and once answered, its result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown or expired verification session, or one started neither by this key nor by another key of its customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over this API key's poll budget: wait `Retry-After` seconds, then poll again.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/exchange":{"post":{"operationId":"exchangeResponseCode","tags":["verifications"],"summary":"Release a same-device result, with the response code the person came back with","description":"For a `same_device` verification that is `awaiting_return`. Send the verification id YOUR OWN SESSION holds for this browser, never one read from the URL, with the `response_code` the browser arrived at your `returnUrl` with. A code works once, for its own verification only; a wrong, reused or foreign code releases nothing and changes nothing. Only the API key that started the verification may exchange it. Where the service deletes on delivery (I5), the exchange is the delivery: it gets the claims, and deletes them.","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRequest"}}}},"responses":{"200":{"description":"Released: `verified` with the claims, or `failed` with the reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"No `responseCode`, or one that does not release this verification: wrong, already used, from another verification, or the verification is not awaiting its return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown or expired verification session, or one started neither by this key nor by another key of its customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verdicts":{"get":{"operationId":"listVerdicts","tags":["operations"],"summary":"The verdict log","description":"Every verdict your API key's verifications reached, or, where your key is a customer's, those of any of its keys, kept across restarts: verdicts, issuers and the names of disclosed claims, never their values. Newest first. Where the service deletes on delivery (I5): the verdict, the credential type and the duration, and as `reason` a refusal's category only; no `issuer`, `certifiedIssuer`, `disclosedClaimNames` or `reference`, and no reason's words, which name the issuer's certificate and the claims, however old the verdict (decision 0099).","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"since","in":"query","required":false,"description":"Only verdicts at or after this ISO 8601 date or time.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many to return, 1 to 1000. Defaults to 100.","schema":{"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"The verdicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerdictList"}}}},"400":{"description":"`since` or `limit` is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/metrics":{"get":{"operationId":"getMetrics","tags":["operations"],"summary":"Counters, trust-list health and recent verdicts","description":"Counters and recent verdicts are per instance and reset on restart; the usage count is kept.","security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"The operational view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metrics"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage-report":{"get":{"operationId":"getUsageReport","tags":["operations"],"summary":"The monthly usage report an installation sends VerySafe","description":"In the `relying-party` role any key reads it. In the `intermediary` role it adds the counts per customer, and only a key that belongs to no customer reads it.","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"month","in":"query","required":true,"description":"The month, as YYYY-MM.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}],"responses":{"200":{"description":"The report, signed and readable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReportResponse"}}}},"400":{"description":"`month` is missing, not YYYY-MM, or has not started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"In the `intermediary` role, the key is a customer's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mcp":{"post":{"operationId":"mcp","tags":["agents"],"summary":"The Model Context Protocol endpoint, for AI agents (JSON-RPC 2.0)","description":"Tools: `list_supported_credential_types`, `verify_credential`, `check_verification`. Verdicts only: no claim values are ever returned here. A verification started here is `cross_device` by declaration: an agent holds no browser session to bind it to. Errors are JSON-RPC errors in a 200 response.\n\nServed only when `MCP_ENABLED` is true (the default).","security":[{"apiKey":[]},{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"A JSON-RPC result or error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"400":{"description":"The body cannot be read: not JSON, say.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mcp/tools":{"get":{"operationId":"listMcpTools","tags":["agents"],"summary":"The agent tools, without JSON-RPC","description":"Served only when `MCP_ENABLED` is true (the default).","security":[{"apiKey":[]},{"bearer":[]}],"responses":{"200":{"description":"The tools an agent sees.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolList"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"operationId":"getHealth","tags":["service"],"summary":"Whether the service is up","security":[],"responses":{"200":{"description":"Up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ready":{"get":{"operationId":"getReadiness","tags":["service"],"summary":"Whether the service can verify: its database answers and its trusted lists have anchors","description":"For a load balancer's or Kubernetes' readiness check. `/health` only says the process is up.","security":[],"responses":{"200":{"description":"Ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not ready: the failing check is named.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}}}}},"/health/retention":{"get":{"operationId":"getRetention","tags":["service"],"summary":"Whether disclosed claims are deleted on time","description":"For an uptime check that alerts. Answers from the database: whether any verification is older than its retention (60 minutes) plus two sweep intervals (10 minutes), which a sweep that runs never allows. A yes or no only, never a count or an age. Not part of `/ready`: a late sweep does not stop a verification.","security":[],"responses":{"200":{"description":"Nothing is kept past its retention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Retention"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Something is kept past its retention, or the database did not answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Retention"}}}}}}},"/healthz":{"get":{"operationId":"getHealthz","tags":["service"],"summary":"The same, for container probes","description":"Some managed front ends answer `/healthz` themselves (Google's does): monitor `/health` from outside.","security":[],"responses":{"200":{"description":"Up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["operations"],"summary":"Your webhook deliveries","description":"Every delivery to your webhook URL, newest first: pending, delivered or failed. A delivered or failed one is kept, and can be replayed, for 30 days after it settled, then deleted (C80). A delivery is one result pushed to your endpoint; each attempt POSTs a `WebhookPayload` with a `Signature` header, a detached JWS (RFC 7515, RFC 7797) over the exact body, ES256, whose protected header names the key (`kid`, in `GET /.well-known/jwks.json`), the delivery (`jti`) and the time (`iat`); `webhook-id` and `webhook-timestamp` repeat the last two. Answer 2xx within 10 seconds to acknowledge; anything else is retried after 30 s, 2 min, 10 min, 30 min, 2 h and 6 h, then the delivery is `failed`. Redirects are not followed. The acknowledgement is the delivery of the result: where the service deletes on delivery, the claims are gone from it afterwards (I5). A same-device result is pushed only after its exchange. Register the URL with the service's operator (the customer record).","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Only deliveries in this state.","schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"limit","in":"query","required":false,"description":"How many to return, 1 to 1000. Defaults to 100.","schema":{"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"The deliveries. Empty for a key of no customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"`status` or `limit` is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-deliveries/{id}/replay":{"post":{"operationId":"replayWebhookDelivery","tags":["operations"],"summary":"Queue a delivery again","description":"Queues a delivered or failed delivery of yours again, due now, its attempts reset. The payload is built afresh at each attempt: a result whose claims were delivered, or that the retention sweep has taken, is pushed without them. It goes to your webhook URL as it is now, and fails at once if you have none (decision 0101).","security":[{"apiKey":[]},{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Queued again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"description":"No valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No delivered or failed delivery of yours with that id; a pending one cannot be replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/jwks.json":{"get":{"operationId":"getWebhookJwks","tags":["service"],"summary":"The keys webhook deliveries are signed with","description":"A JWK Set (RFC 7517) with the public key the `Signature` header of every webhook delivery verifies against, by its `kid`. Fetch it when a delivery names a `kid` you do not hold; keys change only when the operator rotates them. Empty while the service has no signing key.","security":[],"responses":{"200":{"description":"The keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Jwks"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/security.txt":{"get":{"operationId":"getSecurityTxt","tags":["service"],"summary":"Where to report a vulnerability (RFC 9116)","description":"A `security.txt` file (RFC 9116): `Contact`, the address or page to report a vulnerability to; `Expires`, after which to fetch it again; `Canonical`, this file's own address; `Policy`, the security policy's page, when published; `Preferred-Languages`. Public and keyless. Cacheable for an hour.\n\nServed only when `SECURITY_CONTACT` is set.","security":[],"responses":{"200":{"description":"The file.","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conformance.json":{"get":{"operationId":"getConformanceRecord","tags":["service"],"summary":"What this product is certified for, and this build's version","description":"Served only when `CONFORMANCE_RECORD_ENABLED` is true (the default).","security":[],"responses":{"200":{"description":"The conformance record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConformanceRecord"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getApiDescription","tags":["service"],"summary":"This API's description, in OpenAPI 3.1","description":"This document, as the running build describes itself. Cacheable for an hour.\n\nServed only when `OPENAPI_ENABLED` is true (the default).","security":[],"responses":{"200":{"description":"The API's description (OpenAPI 3.1).","content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/docs":{"get":{"operationId":"getApiReference","tags":["service"],"summary":"This API, browsable, with a \"try it\"","description":"Swagger UI reading this service's `/openapi.json`, served from this origin with the two files it needs. A `/v1` call from it needs an API key entered on the page, which stays in the page's memory. VerySafe's sandbox serves it; its production service does not.\n\nServed only when `API_DOCS_ENABLED` is true (off by default).","security":[],"responses":{"200":{"description":"The page.","content":{"text/html":{"schema":{"type":"string"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/docs/swagger-ui.css":{"get":{"operationId":"getApiReferenceStylesheet","tags":["service"],"summary":"The reference's stylesheet (Swagger UI's, as pinned)","description":"Served only when `API_DOCS_ENABLED` is true (off by default).","security":[],"responses":{"200":{"description":"The stylesheet. Cacheable for an hour.","content":{"text/css":{"schema":{"type":"string"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/docs/swagger-ui-bundle.js":{"get":{"operationId":"getApiReferenceScript","tags":["service"],"summary":"The reference's script (Swagger UI's, as pinned)","description":"Served only when `API_DOCS_ENABLED` is true (off by default).","security":[],"responses":{"200":{"description":"The script. Cacheable for an hour.","content":{"text/javascript":{"schema":{"type":"string"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/request.jwt":{"get":{"operationId":"getRequestObject","tags":["wallet"],"summary":"The signed request object the wallet fetches (OpenID4VP `request_uri`)","description":"Answered within `REQUEST_URI_VALIDITY_SECONDS` of the verification's start, as often as the wallet asks.","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A signed JWT (RFC 9101).","content":{"application/oauth-authz-req+jwt":{"schema":{"type":"string"}}}},"404":{"description":"Unknown, expired, already answered, or past its validity (`REQUEST_URI_VALIDITY_SECONDS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-address rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postRequestObject","tags":["wallet"],"summary":"The signed request object, for a wallet that fetches it by POST (OpenID4VP `request_uri_method=post`)","description":"The wallet's `wallet_nonce` is repeated in the signed request. Answered within `REQUEST_URI_VALIDITY_SECONDS` of the verification's start, as often as the wallet asks.","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"wallet_nonce":{"description":"The wallet's nonce, which the signed request repeats.","type":"string","maxLength":512},"wallet_metadata":{"description":"What the wallet supports, as JSON. Not used.","type":"string"}}}}}},"responses":{"200":{"description":"A signed JWT (RFC 9101).","content":{"application/oauth-authz-req+jwt":{"schema":{"type":"string"}}}},"400":{"description":"A malformed `wallet_nonce`, or the certificate that signed the request can no longer sign it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown, expired, already answered, or past its validity (`REQUEST_URI_VALIDITY_SECONDS`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-address rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/response":{"post":{"operationId":"postWalletResponse","tags":["wallet"],"summary":"Where the wallet posts its answer (OpenID4VP `response_uri`)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/WalletResponse"}}}},"responses":{"200":{"description":"Verified. On a `same_device` verification, with the `redirect_uri` the wallet sends the person to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletRedirect"}}}},"400":{"description":"Refused: the reason. On a `same_device` verification, with the `redirect_uri` too: the person is sent back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletRefusal"}}}},"404":{"description":"Unknown or expired verification session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-address rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/dc-api-response":{"post":{"operationId":"relayDcApiResponse","tags":["verifications"],"summary":"Relay the browser prompt's answer (`flow: dc_api`)","description":"Called by your page, in the person's browser, with no key: post what `navigator.credentials.get` resolved to, unopened. It is refused unless it comes (its `Origin`) from a page this verification's request names and the service still allows, and unless the presentation is bound to that origin (an SD-JWT VC's `aud`, an mdoc's session transcript); then every check a redirect presentation gets. Your own Android app, which asked through Credential Manager, posts what it returned and names its own origin in `origin`; the presentation must be bound to that app. A refusal ends the verification as `failed`. The answer is the verdict only: read the claims from your server with `GET /v1/verifications/{id}`.","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DcApiRelay"}}}},"responses":{"200":{"description":"Verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DcApiVerified"}}}},"400":{"description":"Refused: the reason. Also a body that is not a browser's answer, and a verification that is not `dc_api`, which change nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletRefusal"}}}},"404":{"description":"Unknown or expired verification session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over the limit (1 MiB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"The body is of a content type the operation does not take.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over the per-address rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/test/browser-prompt":{"get":{"operationId":"getBrowserPromptTestPage","tags":["service"],"summary":"A page for testing the browser prompt against a real wallet","description":"Starts a `dc_api` verification with an API key pasted into it, asks the browser for the credential, relays the answer and shows the outcome. For a sandbox: never served by VerySafe's production service.\n\nServed only when `DC_API_TEST_PAGE` is true (off by default; `ENVIRONMENT=production` refuses it).","security":[],"responses":{"200":{"description":"The page.","content":{"text/html":{"schema":{"type":"string"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verifications/{id}/result":{"get":{"operationId":"getResultPage","tags":["wallet"],"summary":"The page a person landed on after answering on the same device, before `flow`","description":"No wallet is sent here any more: a `same_device` one goes to your `returnUrl`, a `cross_device` one nowhere. The verdict only, never the claims, since the person's browser carries no API key; none while a result is held.","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The verdict, as a page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Unknown or expired.","content":{"text/html":{"schema":{"type":"string"}}}},"429":{"description":"Over the per-address rate limit: try again after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The service failed for a reason of its own, which it logs. Not a problem with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in words a person can act on."}},"required":["error"]},"VerificationStatus":{"type":"string","enum":["pending","awaiting_return","verified","failed","expired"],"description":"`pending` until the wallet answers; then `verified` or `failed`; `expired` if it never does. `awaiting_return` only on a `same_device` verification: the wallet has answered, and the result, verdict included, is held until your page exchanges the `response_code` it was sent back with (`POST /v1/verifications/{id}/exchange`); unexchanged when the verification's 15 minutes are up, it is `expired`."},"VerificationFlow":{"type":"string","enum":["same_device","cross_device","dc_api"],"description":"How the person presents. `same_device`: your page, on their phone, opens the wallet, and the wallet sends them back to `returnUrl` with a `response_code` you exchange for the result. `cross_device`: you show a QR code on another screen, the wallet is sent nowhere afterwards, and you read the result with `GET /v1/verifications/{id}`. `dc_api`, the browser prompt: your page passes `dcApiRequests` to `navigator.credentials.get`, the browser asks the wallet (on that device, or a phone nearby) and hands the answer back to your page, which posts it to `dcApiResponseUrl`; you read the result with `GET /v1/verifications/{id}`. Your own Android app may do the same through Credential Manager, from an app origin your customer record registers. A verification is only ever in the flow it was started with."},"CredentialType":{"type":"object","properties":{"id":{"type":"string","description":"What to send as `credentialType`."},"label":{"type":"string"},"format":{"type":"string","description":"The credential format: today `dc+sd-jwt` or `mso_mdoc`."},"vct":{"description":"The SD-JWT VC type, for `dc+sd-jwt`.","type":"string"},"nationalVcts":{"description":"For `dc+sd-jwt`: the national types that extend `vct` (ARF PID_14), each asked for and accepted beside it and trusted through the same list; the PID has four, other types none. Their claims may be named differently (decision 0104).","type":"array","items":{"type":"string"}},"docType":{"description":"The ISO 18013-5 document type, for `mso_mdoc`.","type":"string"},"namespace":{"description":"For `mso_mdoc`: the ISO 18013-5 namespace of a claim named by its element alone. A claim of another namespace, such as a Member State's domestic one (ARF PID_06), is named `namespace/element`: `eu.europa.ec.eudi.pid.de.1/age_over_18` (decision 0107).","type":"string"},"availableClaims":{"type":"array","items":{"type":"string"},"description":"Every claim that may be asked for. A claim one Member State's credential carries, such as Germany's `birth_name`, is refused as undisclosed when another's answers."},"defaultClaims":{"type":"array","items":{"type":"string"},"description":"The claims asked for when `claims` is left out."}},"required":["id","label","format","availableClaims","defaultClaims"]},"CredentialTypeList":{"type":"object","properties":{"credentialTypes":{"type":"array","items":{"$ref":"#/components/schemas/CredentialType"}}},"required":["credentialTypes"]},"RequestedCredential":{"type":"object","properties":{"credentialType":{"type":"string","description":"One of `GET /v1/credential-types`, each once in `credentials`."},"claims":{"description":"The claims to ask of it. Ask for the fewest that answer your question. Defaults to the type's defaults.","type":"array","items":{"type":"string"}}},"required":["credentialType"]},"CredentialSet":{"type":"object","properties":{"options":{"minItems":1,"maxItems":10,"type":"array","items":{"minItems":1,"type":"array","items":{"type":"string"}},"description":"The alternatives, most preferred first: each a list of credential types from `credentials` that together satisfy this set. The EU reference wallet offers the person each option it can satisfy, the first chosen."}},"required":["options"],"description":"A DCQL credential set (OpenID4VP 1.0 §6.2): the wallet presents one of its options. Every set is required; optional sets (`required: false`) are not offered yet."},"StartVerificationRequest":{"type":"object","properties":{"credentialType":{"description":"One of `GET /v1/credential-types`. Defaults to `eu_pid`. To ask for several, use `credentials` instead.","type":"string"},"claims":{"description":"The claims to ask for. Ask for the fewest that answer your question. Defaults to the type's defaults.","type":"array","items":{"type":"string"}},"credentials":{"description":"Several credentials in one request (K2), instead of `credentialType` and `claims`: say, the PID and a driving licence. Without `credentialSets` the wallet must present every one; then every check is run on each, and one that fails refuses them all. The result holds each one's claims, by type, as `credentials`.","minItems":1,"maxItems":4,"type":"array","items":{"$ref":"#/components/schemas/RequestedCredential"}},"credentialSets":{"description":"With `credentials`: which of them are alternatives. `[{\"options\": [[\"eu_pid\"], [\"eu_pid_mdoc\"]]}]` asks for the PID in either format; add `{\"options\": [[\"iso_mdl\"]]}` for a driving licence as well. Every credential must be in some option.","minItems":1,"maxItems":10,"type":"array","items":{"$ref":"#/components/schemas/CredentialSet"}},"reference":{"description":"Your own reference for this check, echoed with its result: letters, digits and . _ : / # -, at most 100. Never personal data: an e-mail address, a name, a phone number or an IBAN is refused.","type":"string","maxLength":100},"metadata":{"description":"Up to 10 more of your own values, by name (lower case, digits, _), each as a reference is. Echoed with the result.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"flow":{"description":"On VerySafe's hosted service `flow` is required: a start without it is refused with a 400 that names it (since 2026-10-13). A self-hosted installation defaults to `cross_device` until a release of its own says otherwise. `dc_api` only where the service allows some page to ask through the browser prompt: one your customer record registers (where your key is a customer's, in the intermediary role), or else one the service's `DC_API_ORIGINS` lists; for every credential type, SD-JWT VC and mdoc.","$ref":"#/components/schemas/VerificationFlow"},"returnUrl":{"description":"Required with `flow: same_device`, refused without it: your page that the wallet sends the person back to, with `response_code` added as a query parameter. https, on an origin your customer record registers (where your key is a customer's, in the intermediary role) or else on one the service's `RETURN_URL_ORIGINS` lists; or http to a loopback address.","type":"string","maxLength":2000},"intendedUse":{"description":"Where your key belongs to a Service with registered intended uses: the id of the one this check is for, which must cover it. Without it, the first registered use that does. The request the wallet sees carries that use's registration certificate, when it has one.","type":"string"},"linkScheme":{"description":"What `authorizationRequestUri` starts with, so that it opens your users' wallets: `openid4vp://` (the default), `haip-vp://` (HAIP 1.0), `eu-eaap://` (which ETSI TS 119 472-2 requires every EUDI wallet to support), `eudi-openid4vp://` or `mdoc-openid4vp://` (the EU reference wallet's own), or the https address a wallet claims as its app link, with no query or fragment. A wallet opens only the schemes it registers, and the rest fail silently on the phone. Not with `flow: dc_api`, which has no link.","type":"string","maxLength":200},"requestUriMethod":{"description":"How the wallet fetches the signed request: `get` (the default), or `post`, for a wallet that takes only that, as Moldova's EVO does. Not with `flow: dc_api`, which has no link.","type":"string","enum":["get","post"]},"dcApiProtocols":{"description":"`dc_api` only: which protocols your page offers the browser, in the order `dcApiRequests` lists them. `openid4vp-v1-signed` (the default, alone) is OpenID4VP, which Chrome and the wallets answer; `org-iso-mdoc` is the ISO mdoc protocol (ISO/IEC 18013-7 Annex C), the only one Safari offers, and Chrome on an iPhone with it, so an iPhone's wallet can answer; only for an mdoc credential type (`eu_pid_mdoc`, `iso_mdl`). Offer both, and the browser picks the one it has. Refused with any other flow.","type":"array","items":{"type":"string","enum":["openid4vp-v1-signed","org-iso-mdoc"]}},"dcApiOrigin":{"description":"With `org-iso-mdoc` in `dcApiProtocols`: the origin of your page that will ask (`https://shop.example`), one of the browser origins your customer record registers, or else of the service's `DC_API_ORIGINS`. That request is made for one page: it is signed over its origin. Not needed when exactly one origin is registered. Refused without `org-iso-mdoc`.","type":"string"},"transactionData":{"description":"What the person confirms beyond who they are, such as a payment (OpenID4VP 1.0 §5.1, `transaction_data`): up to 10 entries. Only for an intended use that registers each entry's type, only an SD-JWT VC can confirm it, and not over `org-iso-mdoc`. The check is verified only if the wallet signed every entry, exactly as sent, into the credential's key-binding JWT; a changed or missing entry refuses it. A wallet confirms only types it knows: the EU reference wallets do not list TS12's.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"The transaction data type, such as EU TS12's `urn:eudi:sca:payment:1`. One your intended use registers."},"credentialIds":{"description":"The credential types of this request that may confirm it, each an SD-JWT VC. Without it, every credential the request asks for, which must then all be SD-JWT VCs.","type":"array","items":{"type":"string"}}},"required":["type"],"additionalProperties":{},"description":"One thing the person confirms: its `type`, and the members its type defines, carried as given (for TS12, `payload`). Not `credential_ids` or `transaction_data_hashes_alg`, which the service sets."}}}},"ExchangeRequest":{"type":"object","properties":{"responseCode":{"type":"string","minLength":1,"maxLength":512,"description":"The `response_code` query parameter the person's browser arrived at your `returnUrl` with."}},"required":["responseCode"]},"DcApiRequest":{"anyOf":[{"type":"object","properties":{"protocol":{"type":"string","const":"openid4vp-v1-signed","description":"OpenID4VP 1.0 Appendix A.1: a request signed with JWS Compact Serialization."},"data":{"type":"object","properties":{"request":{"type":"string","description":"The request, signed with the service's access certificate. It names the pages that may use it (`expected_origins`), and asks for an answer encrypted to a key minted for this verification (`dc_api.jwt`)."}},"required":["request"]}},"required":["protocol","data"]},{"type":"object","properties":{"protocol":{"type":"string","const":"org-iso-mdoc","description":"ISO/IEC 18013-7 Annex C: the ISO mdoc protocol, Safari's only one. Offered when `dcApiProtocols` names it."},"data":{"type":"object","properties":{"deviceRequest":{"type":"string","description":"The ISO/IEC 18013-5 DeviceRequest, CBOR as base64url: one DocRequest for the credential asked for, with reader authentication signed by the service's access certificate over the page named in `dcApiOrigin`."},"encryptionInfo":{"type":"string","description":"The EncryptionInfo, CBOR as base64url: a nonce and the key minted for this verification, which the wallet encrypts its answer to (HPKE)."}},"required":["deviceRequest","encryptionInfo"]}},"required":["protocol","data"]}]},"DcApiRelay":{"type":"object","properties":{"protocol":{"type":"string","enum":["openid4vp-v1-signed","org-iso-mdoc"],"description":"The `protocol` of the browser's answer."},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The `data` of the browser's answer, unopened: `{\"response\": \"<encrypted JWT>\"}` for OpenID4VP, `{\"response\": \"<encrypted DeviceResponse, base64url>\"}` for the ISO mdoc protocol, or the wallet's `{\"error\": …}`."},"origin":{"description":"From your own Android app only, which sends no `Origin` header: the app's origin, `android:apk-key-hash:<base64 SHA-256 of its signing certificate>`, as your customer record registers it. A page leaves it out: its origin is its `Origin` header.","type":"string"}},"required":["protocol","data"]},"DcApiVerified":{"type":"object","properties":{"status":{"type":"string","const":"verified","description":"The presentation was verified. Read the claims from your server, with `GET /v1/verifications/{id}`."}},"required":["status"]},"VerificationStarted":{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/VerificationStatus"},"flow":{"$ref":"#/components/schemas/VerificationFlow"},"credentialType":{"description":"The credential type asked for, when the start asked for one.","type":"string"},"requestedClaims":{"description":"The claims asked for, when the start asked for one credential.","type":"array","items":{"type":"string"}},"credentials":{"type":"array","items":{"type":"object","properties":{"credentialType":{"type":"string"},"claims":{"type":"array","items":{"type":"string"}}},"required":["credentialType","claims"]},"description":"Every credential asked for, with the claims asked of it: one, or the several `credentials` named."},"credentialSets":{"description":"The sets of alternatives, as the start named them.","type":"array","items":{"$ref":"#/components/schemas/CredentialSet"}},"authorizationRequestUri":{"description":"Show this to the person as a QR code or a link; their wallet opens it. It starts with `linkScheme`. Every flow but `dc_api`.","type":"string"},"dcApiRequests":{"description":"`dc_api` only: what your page passes to `navigator.credentials.get({ digital: { requests: dcApiRequests } })`, one entry per protocol in `dcApiProtocols`, in that order.","type":"array","items":{"$ref":"#/components/schemas/DcApiRequest"}},"dcApiResponseUrl":{"description":"`dc_api` only: where your page posts what `navigator.credentials.get` resolved to, as `{protocol, data}` (`POST /v1/verifications/{id}/dc-api-response`).","type":"string"},"pollUrl":{"type":"string","description":"Where to read the outcome: `GET /v1/verifications/{id}`."},"reference":{"description":"Your reference, as you sent it.","type":"string"},"metadata":{"description":"Your metadata, as you sent it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"intendedUse":{"description":"The registered intended use this check is for, where your key's Service has registered uses.","type":"string"}},"required":["id","status","flow","credentials","pollUrl"]},"Verification":{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/VerificationStatus"},"flow":{"$ref":"#/components/schemas/VerificationFlow"},"createdAt":{"type":"string","description":"ISO 8601."},"reference":{"description":"Your reference, as you sent it.","type":"string"},"metadata":{"description":"Your metadata, as you sent it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"result":{"description":"Present once the wallet has answered, except while `awaiting_return`. On a same-device verification that expired unexchanged, only `verifiedAt`. Once delivered (`deliveredAt`), without `claims`.","type":"object","properties":{"verifiedAt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"When the wallet answered, in milliseconds since 1970-01-01 UTC."},"claims":{"description":"The disclosed claims, by name: present when `status` is `verified`, for a start that asked for one credential.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"credentials":{"description":"For a start that asked for several credentials (`credentials`), when `status` is `verified`: each presented credential's disclosed claims, by its credential type. With `credentialSets`, only the option the person chose.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"claims":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["claims"]}},"failureReason":{"description":"Why it was refused: present when `status` is `failed`.","type":"string"}},"required":["verifiedAt"]},"deliveredAt":{"description":"ISO 8601. Where the service deletes on delivery (I5): when the result was delivered, after which its claims are gone. Present on the delivering answer and every later one; absent elsewhere.","type":"string"}},"required":["id","status","flow","createdAt"]},"VerdictRecord":{"type":"object","properties":{"sessionId":{"type":"string"},"verdict":{"type":"string","enum":["verified","failed","expired"]},"issuer":{"description":"What the credential says its issuer is (`iss`), when it says: the credential's own claim, which nothing checks. A credential need not carry one, and an mdoc never does. The issuer that was proved is `certifiedIssuer`. On a verdict for several credentials (K2), each presented credential's on a line of its own, as `type: value`, in the order asked; so is `reason`.","type":"string"},"certifiedIssuer":{"description":"On a verified verdict: the issuer its certificate proved, as the subject of the signing certificate the credential's signature verified against, chained to a trust anchor, as its distinguished name (`CN=…, organizationIdentifier=…, O=…, C=…`). For SD-JWT VC and mdoc alike. On a verdict for several credentials (K2), each presented credential's on a line of its own, as `type: value`, in the order asked; so is `reason`.","type":"string"},"issuerTrustStatus":{"description":"The issuer-trust decision: trusted, unknown or blocked.","type":"string"},"reason":{"description":"Why the verdict came out this way, in words an operator can act on. Where the service deletes on delivery (I5): a refusal's category only (`issuer_not_trusted`, `claims_not_disclosed`, `credential_validity`, …), an expiry's fixed sentence, and none on a verified verdict (decision 0099).","type":"string"},"credentialType":{"type":"string","description":"The credential type asked for; for several (K2), their types in the order asked, joined with `+`."},"disclosedClaimNames":{"description":"The NAMES of the claims disclosed, never their values; for several credentials, each as `type/claim`.","type":"array","items":{"type":"string"}},"durationMs":{"description":"From the start of the verification to its verdict.","type":"number"},"reference":{"description":"Your reference, as you sent it.","type":"string"},"at":{"type":"string","description":"ISO 8601."}},"required":["sessionId","verdict","credentialType","at"]},"VerdictList":{"type":"object","properties":{"verdicts":{"type":"array","items":{"$ref":"#/components/schemas/VerdictRecord"}}},"required":["verdicts"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","description":"The delivery id: the `jti` of its signature, and the `webhook-id` header."},"sessionId":{"type":"string","description":"The verification it delivers."},"url":{"type":"string","description":"Where it went: your webhook URL as it was when the delivery was queued, then as it was at each attempt. Each attempt, a replay's included, goes to your webhook URL as it is then (decision 0101)."},"status":{"type":"string","enum":["pending","delivered","failed"],"description":"`pending` until your endpoint answers 2xx (`delivered`), or every attempt has failed (`failed`, replayable)."},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Attempts made so far, up to 7."},"nextAttemptAt":{"type":"string","description":"ISO 8601. When the next attempt is due, while pending."},"lastStatus":{"description":"Your endpoint's HTTP status on the last failed attempt, when it answered.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastError":{"description":"Why the last attempt failed, in a sentence.","type":"string"},"createdAt":{"type":"string","description":"ISO 8601."},"updatedAt":{"type":"string","description":"ISO 8601."},"deliveredAt":{"description":"ISO 8601. When your endpoint acknowledged it.","type":"string"}},"required":["id","sessionId","url","status","attempts","nextAttemptAt","createdAt","updatedAt"]},"WebhookDeliveryList":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["deliveries"]},"WebhookPayload":{"type":"object","properties":{"deliveryId":{"type":"string"},"attempt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"at":{"type":"string","description":"ISO 8601. When this attempt was made."},"verdictOnly":{"description":"Present, and `true`, when the retention sweep had taken the verification before this attempt was made: a retry or a replay after your endpoint was unreachable for a while. `verification` then holds only what the verdict log keeps: its `status` is the verdict it ended with (`verified` or `failed`, or `expired` when it ended with none), `result.failureReason` a refusal's reason as the log keeps it, and never a claim or `metadata`. A `verified` status here does not tell you what the claims said: if you need them, start a new verification (decision 0102).","type":"boolean","const":true},"verification":{"description":"The verification as `GET /v1/verifications/{id}` answers it at the time of the attempt: with its claims until they are delivered, by this delivery's acknowledgement or any other door; after that, without them and with `deliveredAt`. Once the retention sweep has taken it, what the verdict log keeps of it, and `verdictOnly` says so.","$ref":"#/components/schemas/Verification"}},"required":["deliveryId","attempt","at","verification"]},"Jwks":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"The public keys webhook deliveries are signed with (RFC 7517), each with its `kid`."}},"required":["keys"]},"TrustHealth":{"type":"object","properties":{"list":{"type":"string","enum":["pid","pub-eaa","wrprc"]},"mode":{"type":"string","enum":["live","checked-in"]},"anchors":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Trust anchors in effect. Zero means every verification is refused."},"isTestHierarchy":{"type":"boolean"},"basis":{"type":"string","description":"Where the anchors came from, and why."},"degraded":{"type":"boolean"},"consecutiveRefreshFailures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lastRefreshSucceededAt":{"type":["string","null"]},"lastError":{"anyOf":[{"type":"object","properties":{"at":{"type":"string"},"message":{"type":"string"}},"required":["at","message"]},{"type":"null"}]},"signers":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"sha256":{"type":"string","description":"SHA-256 fingerprint, as `openssl x509 -fingerprint -sha256` prints it."},"notAfter":{"type":"string","description":"When it expires, ISO 8601."},"source":{"type":"string","enum":["setting","built-in"],"description":"From the list's settings, or the EU sandbox anchor built into the image."},"status":{"type":"string","enum":["valid","expiring","expired","not-yet-valid"],"description":"`expiring` within 60 days of `notAfter`. Expired, the list can no longer load."}},"required":["subject","sha256","notAfter","source","status"]},"description":"The certificates this list's signer must be, or chain to: the root of its trust (decision 0056)."}},"required":["list","mode","anchors","isTestHierarchy","basis","degraded","consecutiveRefreshFailures","lastRefreshSucceededAt","lastError","signers"]},"LicenceState":{"type":"object","properties":{"required":{"type":"boolean","const":true,"description":"Always true: every installation needs a licence, in either deployment role (decision 0094)."},"role":{"type":"string","enum":["relying-party","intermediary"],"description":"The deployment role this installation runs in."},"status":{"type":"string","enum":["valid","expiring","grace","expired","invalid"],"description":"`invalid`: no licence, one that does not verify, one not yet valid, or one for another role."},"allowsNewVerifications":{"type":"boolean"},"message":{"type":"string"},"customer":{"description":"The licensee: a customer, a partner platform or VerySafe itself.","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"licensedRole":{"description":"The role the installed licence grants. Another than `role` makes the state `invalid`.","type":"string","enum":["relying-party","intermediary"]},"licenceId":{"type":"string"},"expiresAt":{"type":"string"},"daysLeft":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["required","role","status","allowsNewVerifications","message"],"description":"The licence this installation runs under. A production installation starts verifications only while `allowsNewVerifications` is true; a sandbox one always does, and only warns."},"Metrics":{"type":"object","properties":{"counters":{"type":"object","properties":{"verificationsStarted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verdicts":{"type":"object","properties":{"verified":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["verified","failed","expired"]},"refusalsByCause":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["verificationsStarted","verdicts","refusalsByCause"]},"trust":{"anyOf":[{"$ref":"#/components/schemas/TrustHealth"},{"type":"null"}],"description":"The PID list's health; null before the first check."},"trustLists":{"type":"object","properties":{"pid":{"anyOf":[{"$ref":"#/components/schemas/TrustHealth"},{"type":"null"}]},"pub-eaa":{"anyOf":[{"$ref":"#/components/schemas/TrustHealth"},{"type":"null"}]},"wrprc":{"anyOf":[{"$ref":"#/components/schemas/TrustHealth"},{"type":"null"}]}},"description":"Every list's health, by kind: `wrprc`, the registration-certificate providers' list, only when `WRPRC_TRUSTED_LIST_URL` is set."},"licence":{"$ref":"#/components/schemas/LicenceState"},"recentVerdicts":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"verdict":{"type":"string","enum":["verified","failed","expired"]},"issuer":{"description":"What the credential says its issuer is (`iss`), when it says: the credential's own claim, which nothing checks. A credential need not carry one, and an mdoc never does. The issuer that was proved is `certifiedIssuer`. On a verdict for several credentials (K2), each presented credential's on a line of its own, as `type: value`, in the order asked; so is `reason`.","type":"string"},"certifiedIssuer":{"description":"On a verified verdict: the issuer its certificate proved, as the subject of the signing certificate the credential's signature verified against, chained to a trust anchor, as its distinguished name (`CN=…, organizationIdentifier=…, O=…, C=…`). For SD-JWT VC and mdoc alike. On a verdict for several credentials (K2), each presented credential's on a line of its own, as `type: value`, in the order asked; so is `reason`.","type":"string"},"issuerTrustStatus":{"description":"The issuer-trust decision: trusted, unknown or blocked.","type":"string"},"reason":{"description":"Why the verdict came out this way, in words an operator can act on. Where the service deletes on delivery (I5): a refusal's category only (`issuer_not_trusted`, `claims_not_disclosed`, `credential_validity`, …), an expiry's fixed sentence, and none on a verified verdict (decision 0099).","type":"string"},"credentialType":{"type":"string","description":"The credential type asked for; for several (K2), their types in the order asked, joined with `+`."},"disclosedClaimNames":{"description":"The NAMES of the claims disclosed, never their values; for several credentials, each as `type/claim`.","type":"array","items":{"type":"string"}},"durationMs":{"description":"From the start of the verification to its verdict.","type":"number"},"reference":{"description":"Your reference, as you sent it.","type":"string"},"at":{"type":"string","description":"ISO 8601."},"apiKeyId":{"description":"A digest of the API key that started it: yours, or, where your key is a customer's, another of that customer's keys.","type":"string"}},"required":["sessionId","verdict","credentialType","at"]}},"usageEventCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Usage events recorded so far, read from the store at most once a minute per instance."},"note":{"type":"string"}},"required":["counters","trust","trustLists","licence","recentVerdicts","usageEventCount","note"]},"UsageReport":{"type":"object","properties":{"type":{"type":"string","const":"verysafe-usage-report"},"version":{"type":"number","const":1},"installationId":{"type":"string"},"licenceId":{"type":"string"},"customerId":{"type":"string"},"softwareVersion":{"type":"string"},"period":{"type":"object","properties":{"month":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"}},"required":["month","from","to"]},"generatedAt":{"type":"string"},"totals":{"type":"object","properties":{"verificationsStarted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verified":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["verificationsStarted","verified","failed","expired"]},"byApiKey":{"type":"array","items":{"type":"object","properties":{"apiKeyId":{"type":"string"},"verificationsStarted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["apiKeyId","verificationsStarted"]}},"byCredentialType":{"type":"array","items":{"type":"object","properties":{"credentialType":{"type":"string"},"started":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verified":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["credentialType","started","verified","failed","expired"]}},"byCustomer":{"description":"In the `intermediary` role only: each customer's counts.","type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","description":"The customer record's id, or `(no customer)` for a key of none."},"started":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verified":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["customerId","started","verified","failed","expired"]}}},"required":["type","version","installationId","softwareVersion","period","generatedAt","totals","byApiKey","byCredentialType"]},"UsageReportResponse":{"type":"object","properties":{"filename":{"type":"string","description":"What to call the file `signed` is sent to VerySafe as."},"signed":{"type":"string","description":"The report, signed by this installation (a compact JWS): what you send."},"report":{"description":"The same content, readable.","$ref":"#/components/schemas/UsageReport"},"final":{"type":"boolean","description":"False while the month is still in progress."}},"required":["filename","signed","report","final"]},"JsonRpcRequest":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{"type":["string","number","null"]},"method":{"description":"`initialize`, `tools/list` or `tools/call`.","type":"string"},"params":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"JsonRpcResponse":{"anyOf":[{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":{}},"required":["jsonrpc","id","result"]},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"error":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"}},"required":["code","message"]}},"required":["jsonrpc","id","error"]}]},"McpToolList":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name","description","inputSchema"]}},"credential_types":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["tools","credential_types","note"]},"Health":{"type":"object","properties":{"status":{"type":"string","const":"ok"}},"required":["status"]},"Readiness":{"type":"object","properties":{"status":{"type":"string","enum":["ready","not ready"]},"checks":{"type":"object","properties":{"database":{"type":"string","enum":["ok","unavailable"],"description":"The session store answered within two seconds."},"trust":{"type":"string","enum":["ok","no anchors"],"description":"Every trusted list has trust anchors."}},"required":["database","trust"]}},"required":["status","checks"]},"Retention":{"type":"object","properties":{"status":{"type":"string","enum":["ok","overdue","unknown"],"description":"`ok`: no verification is older than its retention plus the sweep's margin (two sweep intervals). `overdue`: one is, so the sweep that deletes disclosed claims has stopped or is failing. `unknown`: the database did not answer within two seconds."}},"required":["status"]},"ConformanceRecord":{"type":"object","properties":{"type":{"type":"string","const":"verysafe-conformance-record"},"version":{"type":"number","const":2},"product":{"type":"string"},"runningVersion":{"type":"string"},"runningCommit":{"type":"string"},"runningVersionIsCertified":{"type":"boolean","description":"Whether this build is a certified one: its version and commit."},"certifications":{"type":"array","items":{"type":"object","properties":{"programme":{"type":"string"},"certifiedProduct":{"type":"string"},"certifiedVersion":{"type":"string"},"releaseCommit":{"type":"string"},"grantedOn":{"type":"string"},"profiles":{"type":"array","items":{"type":"string"}},"credentialFormats":{"type":"array","items":{"type":"string"}},"responseModes":{"type":"array","items":{"type":"string"}},"testPlans":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"register":{"type":"string"},"expires":{"type":"null"}},"required":["programme","certifiedProduct","certifiedVersion","releaseCommit","grantedOn","profiles","credentialFormats","responseModes","testPlans","register","expires"]}},"notice":{"type":"string"}},"required":["type","version","product","runningVersion","runningCommit","runningVersionIsCertified","certifications","notice"]},"WalletResponse":{"type":"object","properties":{"response":{"description":"`direct_post.jwt`: the encrypted response (a JWE).","type":"string"},"vp_token":{"description":"`direct_post`: the presentation, unencrypted.","type":"string"},"state":{"type":"string"}}},"WalletRedirect":{"type":"object","properties":{"redirect_uri":{"description":"`same_device` only: where the wallet sends the person next, your `returnUrl` with `response_code` (HAIP 1.0 §5.1). Absent on a `cross_device` verification, whose wallet stops here (OpenID4VP 1.0 §8.2).","type":"string"}}},"WalletRefusal":{"type":"object","properties":{"error":{"type":"string","description":"Why the presentation was refused."},"redirect_uri":{"description":"`same_device` only: where the wallet sends the person next, your `returnUrl` with `response_code` (HAIP 1.0 §5.1). Absent on a `cross_device` verification, whose wallet stops here (OpenID4VP 1.0 §8.2).","type":"string"}},"required":["error"]}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key."},"bearer":{"type":"http","scheme":"bearer","description":"The same key, as `Authorization: Bearer <key>`."}}}}