OID4VP Verifier Service

The OID4VP Verifier service implements the verifier (relying party) side of OpenID for Verifiable Presentations. It handles both same-device and cross-device verification flows, supports DCQL queries and presentation definitions for specifying which credentials to request, and exposes two API surfaces for different callers: wallet-facing OID4VP endpoints and a verifier-facing Universal OID4VP adapter.

Wallet-Facing OID4VP Endpoints

These endpoints face the holder wallet. They serve request objects to wallets and process the direct_post responses that come back. They are the verifier-side OID4VP protocol endpoints, not a lower layer that the Universal OID4VP adapter builds on top of.

Method	Path	Description
GET	/request/{id}	Serve an authorization request object. The wallet fetches this URL (from the request_uri in the QR code or deep link) to retrieve the full request parameters, including the DCQL query or presentation definition, nonce, and response URI.
POST	/request/{id}	Same as GET but accepts POST, for wallets that prefer it.
POST	/response	Receive the holder's direct_post response containing the verifiable presentation(s). The service validates the presentation, checks the nonce, verifies credential signatures, and evaluates the DCQL query or presentation definition against the submitted data.

Universal OID4VP Adapter

The Universal OID4VP adapter is the verifier-facing API for the party web app or backend that is initiating verification. It follows the Universal OID4VP model and manages verification sessions, QR code creation, and status polling. This is the recommended integration point for verifier applications that do not want to manage low-level OID4VP message exchange themselves.

Method	Path	Description
POST	/oid4vp/backend/auth/requests	Create a verification session. Accepts a DCQL query (inline or by query_id reference), optional webhook callback configuration, TTL, and QR code styling. Returns the session correlation ID, QR code data URI, status polling URL, and the openid4vp:// request URI.
GET	/oid4vp/backend/auth/requests/{correlationId}	Check verification session status. Returns the current state (CREATED, REQUEST_RETRIEVED, AUTHORIZATION_RESPONSE_RECEIVED, AUTHORIZATION_RESPONSE_VERIFIED, ERROR, EXPIRED) and, when verification succeeds, the verified credential data.
DELETE	/oid4vp/backend/auth/requests/{correlationId}	Delete a verification session. Sessions expire automatically based on their TTL, but you can remove them explicitly if a user cancels or navigates away.

Including in Your Server

build.gradle.kts

dependencies {
    // Includes both the wallet-facing OID4VP endpoints and the Universal OID4VP adapter
    implementation("com.sphereon.idk:services-oid4vp-verifier-rest:0.25.0")
}

Configuration

• DCQL queries: Pre-configure named queries that can be referenced by query_id in the Universal OID4VP adapter, so your frontend does not need to construct queries itself.
• Client ID and scheme: Set the verifier's clientId and clientIdScheme (e.g., redirect_uri, x509_san_dns). When using X.509 schemes, configure the signing key for JAR (JWT-Secured Authorization Requests).
• Response mode: Defaults to direct_post. The wallet posts its presentation to the wallet-facing verifier response endpoint.
• Webhook callbacks: In the Universal OID4VP adapter, configure a callback URL and specify which status transitions trigger the webhook. You can include the verified credential data in the callback payload.
• Session TTL: Set the default time-to-live for verification sessions (default: 600 seconds).
• QR code styling: Configure default QR code size, foreground color, and background color for the Universal OID4VP adapter.

See OID4VP Verifier for the wallet-facing OID4VP API and Universal OID4VP for the verifier-facing Universal OID4VP adapter.

Docker

Each service ships with a Dockerfile and docker-compose configuration in its container/ directory.

Building the image

# Build the fat JAR first
./gradlew :services-oid4vp-verifier-rest:buildFatJar

# Build the Docker image
docker compose -f services/oid4vp-verifier/container/docker-compose.yaml build

Running with Docker Compose

docker compose -f services/oid4vp-verifier/container/docker-compose.yaml up

The service starts on port 8080. Configuration is loaded from container/config/ inside the image. Override settings via environment variables in a .env file next to the docker-compose.yaml.

Image details

Property	Value
Base image	eclipse-temurin:21-jre
Docker image	sphereon/idk-oid4vp-verifier:latest
Exposed port	8080
Config location	/app/config/

Next Steps

• Services Overview for an introduction to all available IDK services and the CommandBackedHttpAdapter pattern
• OID4VP Verifier Guide for the wallet-facing OID4VP API reference
• Universal OID4VP Guide for the verifier-facing Universal OID4VP adapter
• OID4VCI Issuer for credential issuance, the complement to verification
• Ktor Integration for details on installing and configuring the KotlinInjectPlugin