Flows and user experience

OpenID4VP supports multiple UX patterns for connecting a verifier with a wallet. The protocol stays the same, but the transport and user interaction can differ depending on whether the verifier and wallet are on the same device.

Same-device vs cross-device

Same-device flow: The verifier opens the wallet on the same device, typically using a redirect or deep link.

Cross-device flow: The verifier shows a QR code on one device and the wallet scans it from another device.

A key concept in cross-device flows is keeping the QR code small. Instead of embedding a large request directly in the QR code, the verifier can include a request_uri that points to a hosted Request Object.

Direct post response modes

OpenID4VP defines response modes for returning the authorization response back to the verifier.

direct_post: The wallet sends the response as an HTTPS POST.
direct_post.jwt: The wallet sends an encrypted JWT-based response (typically a JWE).

In direct_post flows, the verifier provides a response_uri in the authorization request. The wallet posts the authorization response (including vp_token) to that endpoint.

sequenceDiagram
    participant Verifier
    participant Wallet
    participant Holder

    Verifier->>Wallet: Authorization request
    Wallet->>Holder: Ask for consent
    Holder->>Wallet: Approve
    Wallet->>Verifier: HTTPS POST to response_uri (vp_token)
    Verifier->>Verifier: Validate response

Cross-device flow with request_uri

In a cross-device flow, the verifier typically uses a QR code that points at a request_uri.

sequenceDiagram
    participant Verifier
    participant Wallet
    participant Holder

    Verifier->>Wallet: QR code (includes request_uri)
    Wallet->>Verifier: Fetch Request Object (GET/POST)
    Wallet->>Holder: Ask for consent
    Holder->>Wallet: Approve
    Wallet->>Verifier: HTTPS POST to response_uri (vp_token)

Digital Credentials API (DC API)

OpenID4VP also defines response modes for integration with the W3C Digital Credentials API:

dc_api
dc_api.jwt

These flows are designed for browser-mediated wallet invocation. See Digital Credentials API integration for details.

For background on the underlying browser API (including navigator.credentials.get(), protocol identifiers, and Permissions Policy), see Digital Credentials API.

Role in Vidos

Vidos supports OpenID4VP flows that return results back to the verifier using:

direct_post and direct_post.jwt
dc_api and dc_api.jwt

This design avoids redirect-fragment–based response delivery, and it aligns with how Vidos services handle verifiable presentation verification.