Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Verifier

The Verifier is a core component of the EVDI (Empeiria's End-to-End Verifiable Data Infrastructure) ecosystem. It requests and validates Verifiable Presentations (VPs) from wallets and checks the Verifiable Credentials (VCs) inside them, using the OpenID4VP protocol over a standards-based HTTP API. Acting as the relying party between wallets and your application, the Verifier lets you build credential-based access control and passwordless login flows on top of cryptographically verifiable claims.

Key Highlights:

  • Standards Alignment Implements OpenID4VP for presentation requests and verifies W3C-aligned Verifiable Credentials in two formats: SD-JWT VC (dc+sd-jwt), which honors selective disclosure so holders reveal only the claims you ask for, and JWT-VC-JSON (jwt_vc_json). Three OpenID4VP draft versions are supported: v1 (default), v1.draft21, and v1.draft24.

  • Flexible Credential Queries Request exactly the credentials and claims you need using either a DCQL query or a DIF Presentation Exchange v2 definition. Each authorization request must carry exactly one of the two.

  • Multiple Response Modes Authorization requests can use direct_post, direct_post.jwt (default), or the Digital Credentials API modes dc_api and dc_api.jwt, so you can integrate with both redirect-based wallets and in-browser credential APIs.

  • Real-Time Feedback Each request creates a verification session whose state you can poll, or subscribe to over Server-Sent Events (SSE) to receive live updates as the wallet responds and verification completes.

  • Standalone Credential Verification Beyond the full presentation flow, a direct endpoint verifies a single compact credential string (SD-JWT or JWT-VC) and returns its decoded claims — useful for server-to-server checks and testing.

  • Decentralized Identifiers Issuer and holder DIDs using did:web and did:key (Ed25519) are supported today; the service serves its own did:web documents over HTTPS (see Terminology and Concepts for did:empe).

  • Security and Access Controls Verifier endpoints require a valid OIDC JWT Bearer token (Authorization: Bearer <token>), validated against a JWKS endpoint. HTTPS is required in production.

Verifying a Presentation

The typical verifier workflow is: create an authorization request that describes the credentials you need, hand the request URI (or its QR code) to a wallet, then track the verification session until it completes. All requests below require a valid Authorization: Bearer <token> header.

1. Create an Authorization Request

POST /verifiers/:verifierId/authorization-requests

Request Body:

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

  • dcqlQuery: A DCQL query describing the requested credentials and claims. Provide exactly one of dcqlQuery or presentationDefinition.

  • presentationDefinition: A DIF Presentation Exchange v2 definition, as an alternative to dcqlQuery. Requires version to be v1.draft21 or v1.draft24.

  • responseMode: One of direct_post, direct_post.jwt, dc_api, or dc_api.jwt. Defaults to direct_post.jwt.

  • version: OpenID4VP draft version — v1, v1.draft21, or v1.draft24. Defaults to v1, which supports only dcqlQuery; use v1.draft21 or v1.draft24 with presentationDefinition (and note that dcqlQuery cannot be combined with v1.draft21).

  • signingDid: Optional DID used to sign the authorization request. If omitted, the verifierId path parameter must already be a DID.

  • expectedOrigins: Optional list of expected origins for Digital Credentials API flows.

  • authorizationResponseRedirectUri, transactionData, verifierInfo: Optional advanced parameters included in the request.

Response Body:

  • authorizationRequestUri: The openid4vp:// URI the wallet opens to respond to the request.

  • verificationSessionId: Identifier used to track and subscribe to the verification session.

  • authorizationRequestId: Identifier of the hosted request, when applicable.

  • expiresAt: When the request expires, in ISO format.

To obtain a scannable QR code instead of JSON, call POST /verifiers/:verifierId/authorization-requests/qr-code with the same body. It returns a PNG image and exposes the request details in the X-Authorization-Request-Uri, X-Verification-Session-Id, and X-Authorization-Request-Id response headers.

2. Track the Verification Session

GET /verification-sessions/:sessionId

Returns the current session state and request details.

Response Body:

  • state: The session lifecycle state, which advances as the wallet responds (for example RequestCreated).

  • errorMessage: Present when verification fails, describing the last error observed.

3. Subscribe to Live Updates (SSE)

GET /verification-sessions/:sessionId/events

Opens a Server-Sent Events stream for the session. The stream emits a session event carrying the session object (the same shape as the read above) immediately on subscribe — reflecting the session's current state — and again each time the state changes, plus a ping heartbeat every 15 seconds to keep the connection alive. Use it to update your UI in real time while the wallet presents its credentials.

Standalone Credential Verification

To verify a single credential string directly — without a presentation flow — post its compact serialized form.

POST /credentials/verify

Request Body:

  • credential: A compact JWT or SD-JWT credential string.

Response Body (valid):

  • isValid: Whether the credential passed verification.

  • format: The detected credential format. A verified SD-JWT credential returns "dc+sd-jwt"; a verified JWT-VC returns "jwt_vc".

  • payload: The decoded credential payload.

  • prettyClaims: For SD-JWT credentials, all disclosed claims merged into a single object.

Response Body (invalid):

Authentication

All Verifier endpoints are protected. Requests must include a valid OIDC-issued JWT in the Authorization header:

Tokens are validated against a JWKS endpoint (OIDC_JWKS_URL). See Authentication for token validation details and the local-development bypass.

PreviousAuthorizationNextTerminology and Concepts

Last updated