Server-Side VP Queries

This page explains how the Verifier expresses what it wants a holder to present. Every authorization request carries its credential query inline: you build a DCQL query or a Presentation Exchange v2 definition in your application code and send it in the request body when you create the authorization request. Queries live in your codebase, so there are no server-side query records to create, fetch, or delete.

---

Overview

• A verifier asks for credentials by creating an authorization request (an OpenID4VP request). The query that describes the acceptable credentials and fields lives inside that request body.

• You supply the query in one of two ways:

  • dcqlQuery — a Digital Credentials Query Language (DCQL) query, or

  • presentationDefinition — a DIF Presentation Exchange v2 definition.

• Supply exactly one of the two. If neither is supplied, the request fails with 400 Bad Request and the message Either dcqlQuery or presentationDefinition must be provided. Sending both passes the service's own input validation but fails downstream for every version value, surfacing as a 500 (see Query Language).

• Because queries are inline, you standardize them in your own application code and pass the built object on each request, rather than registering reusable query records on the server.

---

Authorization Request Endpoints

These endpoints live under the /verifiers/{verifierId}/authorization-requests path. The verifierId is the identifier of a registered verifier; it may be a DID. Every endpoint requires a valid OIDC JWT Bearer token (Authorization: Bearer <token>; see Authentication).

Create an Authorization Request

POST /verifiers/{verifierId}/authorization-requests

Creates an OpenID4VP authorization request and a verification session.

Request Body

• dcqlQuery (object, optional) A DCQL query describing the requested credential configurations. Required if presentationDefinition is not provided.

• presentationDefinition (object, optional) A DIF Presentation Exchange v2 definition. Required if dcqlQuery is not provided. Can only be used with version v1.draft21 or v1.draft24.

• responseMode (string, optional) How the holder returns the presentation. One of direct_post, direct_post.jwt, dc_api, dc_api.jwt. Defaults to direct_post.jwt.

• version (string, optional) The OpenID4VP draft to use. One of v1, v1.draft21, v1.draft24. Defaults to v1, which supports only dcqlQuery — use v1.draft21 or v1.draft24 with presentationDefinition. Note that dcqlQuery cannot be combined with v1.draft21.

• signingDid (string, optional) The DID that signs the authorization request. If omitted, the verifierId path parameter must itself be a DID; otherwise the request fails with 400 Bad Request.

• authorizationResponseRedirectUri (string, optional) Redirect URI to include in the authorization response.

• expectedOrigins (array of strings, optional) Expected origins for Digital Credentials API flows (used with the dc_api response modes).

• transactionData (array of objects, optional) Transaction data entries to bind into the request.

• verifierInfo (array of objects, optional) Verifier attestations to include in the request.

Response Body

A success response returns the request details:

• authorizationRequestUri — an openid4vp://... URI the wallet opens to fulfill the request.

• verificationSessionId — the session identifier used to track and observe the verification.

• authorizationRequestId — present for hosted requests.

• expiresAt — ISO timestamp when the request expires.

Example request body (DCQL)

{
  "dcqlQuery": {
    "credentials": [
      {
        "id": "employee-badge",
        "format": "dc+sd-jwt",
        "meta": { "vct_values": ["https://issuer.example.com/vct/employee-badge"] },
        "claims": [
          { "path": ["employee_id"] },
          { "path": ["full_name"] },
          { "path": ["department"] }
        ]
      }
    ]
  },
  "responseMode": "direct_post.jwt",
  "version": "v1"
}

Example request body (Presentation Exchange v2)

{
  "presentationDefinition": {
    "id": "employee-badge-check",
    "input_descriptors": [
      {
        "id": "employee-badge",
        "constraints": {
          "fields": [
            {
              "path": ["$.vct"],
              "filter": { "type": "string", "const": "https://issuer.example.com/vct/employee-badge" }
            },
            { "path": ["$.department"] }
          ]
        }
      }
    ]
  },
  "version": "v1.draft24"
}

The version field is required here: presentationDefinition works only with v1.draft21 or v1.draft24.

Example response

{
  "authorizationRequestUri": "openid4vp://?request_uri=...",
  "verificationSessionId": "18b760b1-4ab8-4d38-9d42-6b4c25a4d2e0",
  "authorizationRequestId": "1b8a6a8b-2ac1-4f0b-9d9c-6b9c859b1af2",
  "expiresAt": "2026-06-22T12:34:56.789Z"
}

Create an Authorization Request as a QR Code

POST /verifiers/{verifierId}/authorization-requests/qr-code

Takes the same request body as above, but returns a PNG image of a QR code encoding the authorizationRequestUri. This is convenient for cross-device flows where a holder scans the code with a wallet.

The request URI and session identifiers are returned in response headers:

• X-Authorization-Request-Uri — the openid4vp://... URI.

• X-Verification-Session-Id — the verification session identifier.

• X-Authorization-Request-Id — present for hosted requests.

---

Observing the Result

After a request is created, track its progress through the verification session endpoints:

• GET /verification-sessions/{sessionId} — read the current session state (for example RequestCreated, and later states as the holder responds).

• GET /verification-sessions/{sessionId}/events — a Server-Sent Events (SSE) stream that emits a session event whenever the session updates, plus a ping heartbeat every 15 seconds.

Both endpoints require a valid Bearer token.

---

DCQL vs Presentation Exchange

Both query languages let you target specific credential types and constrain individual claims; pick whichever fits your stack.

• DCQL is the newer, compact query model. It describes requested credentials by format and metadata (such as the SD-JWT vct) and lists the claim paths you need.

• Presentation Exchange v2 uses input descriptors with JSONPath path expressions and JSON Schema (Draft 7) filter rules to validate the value at each path. See the Query Language page for more on paths and filters.

The Verifier accepts either form and uses it to match credentials the holder presents. In a DCQL query, request an SD-JWT VC with the dc+sd-jwt format value (the DIF Claim Format Registry identifier the Verifier uses for SD-JWT credentials).

---

Notes

• Authentication is an OIDC JWT Bearer token; these endpoints require a valid token but no specific role (see Authentication).

• Queries are not persisted as reusable, ID-addressable configurations. Keep your query objects in your own codebase and pass them inline on each request so you can standardize them across flows.