> For the complete documentation index, see [llms.txt](https://docs.empe.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.empe.io/develop/verifier/architecture-overview.md). # 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 `), validated against a JWKS endpoint (see [Authentication](/develop/verifier/authentication.md)). * 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](/develop/verifier/future-enhancements.md)). ## 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: ```json { "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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.empe.io/develop/verifier/architecture-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.