Architecture Overview

The Verifier is the OpenID4VP capability of the EVDI SSI service, exposed as a set of REST and Server-Sent Events (SSE) endpoints. Your application drives a verification by calling these endpoints, rendering the resulting QR code or deep link, and reacting to session state as it changes. This keeps the integration thin: everything is plain HTTP calls plus an SSE subscription, with no library or separate microservice to deploy.

Key Components:

1. Verifier Endpoints:

   • Create OpenID4VP authorization requests scoped to a verifier (POST /verifiers/:verifierId/authorization-requests), describing the credentials you want with a DCQL query or a DIF Presentation Exchange v2 definition.

   • Generate a ready-to-scan PNG QR code for the same request (POST /verifiers/:verifierId/authorization-requests/qr-code).

   • Track a verification session server-side and let you read it on demand (GET /verification-sessions/:sessionId).

   • Stream live session updates over SSE (GET /verification-sessions/:sessionId/events).

   • Verify a standalone credential string without a presentation flow (POST /credentials/verify).

2. Empe DID Wallet:

   • A user's personal wallet application that holds their DIDs and Verifiable Credentials.

   • Scans the QR code or opens the openid4vp:// request URI to fetch the authorization request.

   • Selects matching credentials and submits a Verifiable Presentation back to the Verifier endpoints.

3. Front-End Integration:

   • Your application renders the QR code (or deep link) returned when you create the authorization request.

   • It subscribes to the session's SSE stream and updates the UI as the session moves through its lifecycle, showing the final outcome to the user in real time.

4. Your Backend (Relying Party):

   • Calls the Verifier endpoints with a valid OIDC Bearer token (Authorization: Bearer <token>), validated against a JWKS endpoint (see Authentication).

   • Owns all business logic. The service does not issue application JWTs or sessions for you — when a verification session reaches the ResponseVerified state, your backend decides what that means (log the user in, grant access, create your own session token, and so on).

5. Trust Roots:

   • Issuer and holder identities are Decentralized Identifiers (DIDs) resolved directly by the service. did:web is resolved over HTTPS from the DID's origin; did:key (and did:jwk) are self-describing and need no external lookup. did:web documents created through EVDI are hosted by the service itself.

   • Authorization requests are themselves DID-signed using the verifier's verification method, so wallets can authenticate the requester.

   • Verification covers cryptographic signatures, the credential format, and the presentation itself. Revocation and status-list checks are not part of verification today (see Future Enhancements).

Verification Session Lifecycle

Every authorization request you create is backed by a verification session whose state you can poll or stream. The states are:

• RequestCreated: The authorization request has been created and is waiting to be retrieved by a wallet.

• RequestUriRetrieved: A wallet has fetched the request via its request_uri.

• ResponseVerified: The wallet submitted a presentation and the service verified it successfully. This is your signal to apply business logic.

• Error: The presentation was rejected or the flow failed; errorMessage on the session describes why.

Sessions also carry an expiresAt timestamp. Reading a session returns its full record:

{
  "id": "18b760b1-4ab8-4d38-9d42-6b4c25a4d2e0",
  "verifierId": "did:web:verifier.example.com:8f2c...",
  "state": "ResponseVerified",
  "authorizationRequestId": "1b8a6a8b-2ac1-4f0b-9d9c-6b9c859b1af2",
  "authorizationRequestUri": "openid4vp://?request_uri=...",
  "expiresAt": "2026-06-22T12:34:56.789Z"
}

The SSE stream at GET /verification-sessions/:sessionId/events emits a session event (carrying the record above) on every state change, plus a ping heartbeat roughly every 15 seconds to keep the connection alive. Subscribing to this stream is the recommended way to drive a responsive front-end rather than polling the session endpoint.

This layered design keeps a clear separation of concerns: the service handles request signing, session tracking, and presentation verification against open standards, while your application owns presentation of the QR code, the user experience, and what happens after a credential is verified.