Presentation Flows
OID4VP supports multiple presentation flows to accommodate different verification scenarios. The choice of flow depends on whether the wallet and verifier are on the same device, who initiates the interaction, and whether verification happens online or in-person.
Flow Comparison
| Flow | Trigger | UX | Transport | Use Case |
|---|---|---|---|---|
| Same-Device | Deep link / Custom scheme | App switch | HTTPS | Mobile-native verification |
| Cross-Device | QR code (wallet scans) | Scan & approve on phone | HTTPS | Desktop or kiosk verification |
| Wallet-Initiated | User selects credential | Push from wallet | HTTPS | Online proactive sharing |
| Proximity | QR code (verifier scans) | Show QR, tap approve | BLE / NFC / WiFi | In-person verification |
Same-Device Flow
In the same-device flow, both the relying party application and wallet are on the same device (typically mobile). The verifier triggers the wallet using a custom URL scheme or universal link.
Custom Scheme
openid4vp:// is the standard custom URL scheme. Wallets register to handle this scheme on the device.
Requires wallet app to be installed. May show app chooser if multiple wallets are registered.
Universal Links
Uses HTTPS URLs that wallets claim via apple-app-site-association (iOS) or assetlinks.json (Android).
More reliable and secure. Falls back to browser if wallet not installed.
Deep Link Examples
// iOS/Android Deep Link handling
// Custom scheme
openid4vp://authorize?
response_type=vp_token
&client_id=https://verifier.example.com
&response_mode=direct_post
&response_uri=https://verifier.example.com/callback
&nonce=n-0S6_WzA2Mj
&presentation_definition_uri=https://verifier.example.com/pd/age-check
// Universal Link (iOS) / App Link (Android)
https://wallet.example/verify?
request_uri=https://verifier.example.com/request/xyz789Cross-Device Flow
The cross-device flow handles scenarios where the user is browsing on one device (e.g., desktop) but their wallet is on another (e.g., mobile phone). A QR code bridges the gap.
QR Code Content
The QR code contains the authorization request, typically using request_uri to keep the QR code small and scannable.
// QR Code Content (Cross-Device)
openid4vp://authorize?
request_uri=https://verifier.example.com/request/abc123
&client_id=https://verifier.example.com
// Or using Universal Links
https://wallet.example/.well-known/openid4vp?
request_uri=https://verifier.example.com/request/abc123
&client_id=https://verifier.example.comSession Synchronization
The browser session doesn't automatically know when the mobile wallet completes the presentation. Common approaches:
- WebSocket: Real-time push notification
- Server-Sent Events (SSE): One-way push
- Polling: Periodic status checks (fallback)
Session Status Polling
// Verifier backend: Check presentation status
GET /presentation-status/abc123 HTTP/1.1
Host: verifier.example.com
Authorization: Bearer session-token
// Response (pending)
{
"status": "pending",
"expires_at": "2024-01-15T10:05:00Z"
}
// Response (completed)
{
"status": "completed",
"vp_token_hash": "sha256:abc123...",
"verified_claims": {
"age_over_21": true
}
}Wallet-Initiated Flow (Online)
In the wallet-initiated flow, the user proactively shares a credential from their wallet to an online verifier endpoint. The wallet discovers compatible verifiers via metadata and initiates the presentation over HTTPS without a prior request from the verifier.
Online Flow
This flow is for network-based presentations where the wallet communicates with a verifier's backend over the internet. For in-person scenarios where the verifier scans a QR code from your phone, see the Proximity Flow below.
Use Cases
- Sharing professional certifications with online job portals
- Presenting membership credentials to online services
- Proactively submitting KYC credentials to financial platforms
- Self-service online verification workflows
Proximity Flow (In-Person)
The proximity flow handles in-person verification where the holder displays a QR code on their device and the verifier scans it. Data is transferred locally via BLE, NFC, or WiFi Aware rather than over the internet.
Key Difference
In cross-device OID4VP, the wallet scans a QR code displayed by the verifier. In proximity flow, the verifier scans a QR code displayed by the wallet. This reversal enables offline verification and keeps credential data local.
Device Engagement
The wallet generates a QR code containing connection information (not the credential itself). This establishes a secure channel.
Defined in ISO/IEC 18013-5 for mobile driving licenses (mDL).
Local Transport
After scanning, data transfers over a local channel:
- BLE: Most common, ~10m range
- NFC: Tap-to-share, very short range
- WiFi Aware: Higher bandwidth for large credentials
Use Cases
- Age verification at bars, venues, or retail
- Presenting a mobile driving license at a traffic stop
- Building access with employee credentials
- Event entry with digital tickets
- Healthcare credential verification at clinics
Standards
ISO/IEC 18013-5
The primary standard for mobile driving license (mDL) proximity presentation. Defines device engagement, session encryption, and mdoc data transfer.
OID4VP over BLE
Draft extension to OID4VP for proximity scenarios. Aims to unify the protocol across online and offline presentation modes.
Wallet Metadata
Wallets can advertise their capabilities through metadata, enabling verifiers to craft compatible requests.
// Wallet metadata for discovery
{
"authorization_endpoint": "openid4vp://authorize",
"response_types_supported": ["vp_token"],
"response_modes_supported": ["direct_post", "direct_post.jwt"],
"vp_formats_supported": {
"jwt_vp_json": {
"alg_values_supported": ["ES256", "EdDSA"]
},
"mso_mdoc": {
"alg_values_supported": ["ES256"]
}
},
"request_object_signing_alg_values_supported": ["ES256", "EdDSA"]
}