Skip to main content

Mobile Wallet & Wallet API

Customer backends integrate with Credential Factory and Verification Gateway using authenticated REST APIs (OAuth 2.0 Bearer tokens). Holder wallets — including the iden2 mobile app — call separate Wallet API endpoints that use a different access model: OpenID4VP wallet endpoints use JAR (signed Request Objects verified via JWKS) and OID4VCI wallet endpoints use capability-based access scoped to the offer UUID. Neither requires your OAuth client_secret.

If you are building a custom wallet or debugging holder-side behaviour, this page documents those endpoints. If you only integrate as an issuer or verifier, you can skip this — your QR code drives the wallet flow automatically.

Two surfaces per service​

ServiceYour backend (auth required)Wallet (public)
Verification GatewayPOST/GET /api/v1/verifier/sessions/*/openid4vc/*, /.well-known/jwks.json
Credential FactoryPOST/GET /api/v1/iaas/credential-offers/*, POST /api/v1/issuer/credentials/{credentialId}/revokePOST /api/v1/wallet/offers/{offerId}/response

See Authentication for the distinction between the OAuth Bearer model used by backend APIs and the JAR / capability-based model used by Wallet API endpoints.

Verification flow (OpenID4VP)​

After the holder scans your Verification Gateway QR code:

Your backend learns the outcome by polling GET /api/v1/verifier/sessions/{sessionId} — see Verification Integration Guide.

Verification Gateway Wallet API endpoints​

MethodPathPurpose
GET/openid4vc/request/{sessionId}Request Object JWT (RFC 9101 JAR) — signed by Verification Gateway
POST/openid4vc/verify/{sessionId}Submit VP token
GET/.well-known/jwks.jsonEd25519 public key for Request Object signature verification

Path parameter: {sessionId} is the UUID returned by POST /api/v1/verifier/sessions — the OpenID4VP state value after URL rewriting.

VP submission accepts application/x-www-form-urlencoded (OpenID4VP standard) or application/json:

{
  "vp_token": "<SD-JWT VP>",
  "presentation_submission": "<optional JSON string>"
}

Wallet endpoints are reached via openid4vp:// deep links, not browser XHR.

iden2 wallet behaviour​

  1. Scan QR or open deep link with authorizationUrl
  2. Fetch the JAR Request Object from GET /openid4vc/request/{sessionId}; verify its signature via JWKS
  3. Optionally check verifier trust via Trust Network API using verifier_member_id from client_metadata
  4. Match stored SD-JWT credentials against presentation requirements
  5. Show selective disclosure preview — holder picks fields to reveal
  6. Build VP with KB-JWT holder binding; POST to Verification Gateway
  7. Display success/failure to holder

Trust verification can be disabled in wallet settings (user override).

Issuance flow (OID4VCI)​

After the holder scans your Credential Factory offer QR:

MethodPathBody
POST/api/v1/wallet/offers/{offerId}/response?token=…{"action":"accepted"} or {"action":"rejected"}

Don't build this URL yourself: use the walletResponseUrl returned by Create Credential Offer, unchanged, and get it to the holder's wallet along with the offer. Its token query parameter is the capability — the offer ID alone returns 404. Treat the URL as a secret. The wallet can respond while the offer is pending or after the credential is claimed. Accepting sets status accepted; if the credential hasn't been issued yet, the issuance is recorded on the accepted offer when it happens. Rejecting sets status rejected with failureReason wallet_rejected. Repeating the same answer returns 200 again; a different answer after the offer was settled (for example rejecting after accepting) returns 409.

OID4VCI cryptographic issuance runs through the platform issuer backend. Your issuer integration only creates offers and polls status.

Mobile Wallet SDK (partners)​

Early access

An embeddable Mobile Wallet SDK (Flutter) is available to partners in early access. It provides credential storage, passkey authentication, OID4VCI issuance, OpenID4VP presentation, deep-link dispatch, and trust-network integration for apps that embed iden2 wallet capabilities without shipping the full consumer app. See the Wallet SDK documentation.

If you are not using the SDK:

  • Use the iden2 wallet app for end-to-end testing against staging
  • Build against the Wallet API endpoints above for custom wallet implementations
  • Contact support for SDK access

Building a custom wallet checklist​

  • Handle openid-credential-offer:// and openid4vp:// deep links
  • Support SD-JWT credentials and selective disclosure
  • Implement KB-JWT holder binding on presentation
  • For JAR sessions: fetch Request Object, verify signature via JWKS
  • Call Credential Factory wallet response after successful OID4VCI claim
  • Do not embed issuer/verifier OAuth client credentials (client_id / client_secret) in the app

Next steps​