Skip to main content

Providing Wallets

This page explains how to use the system to be a Wallet Provider. For configuration instructions, see Configure Wallet Provider.

Workflow overview​

Understanding the basic wallet providing workflows helps you integrate they system correctly. The following diagrams show the key processes wallets follow when interacting with a wallet provider.

Wallet registration and activation​

Wallets register during onboarding to establish their identity with the wallet provider:

During registration, the wallet supplies an authentication key that becomes bound to the wallet unit. The wallet provider returns a wallet unit ID that the wallet uses for all subsequent interactions. If app integrity verification is enabled, the wallet must also activate immediately after registration by providing platform-specific attestations.

Status checks​

Wallets check their registration status differently depending on whether Token Status List is enabled for wallet unit attestations.

Without Token Status List:

The wallet calls the attestation issuance endpoint with empty values for both waa and wua. If the wallet unit is active, the provider returns 200 with empty attestation values. If revoked, it returns 400.

With Token Status List:

When Token Status List is enabled, the wallet can check the status list directly, using the same mechanism that credential issuers use to verify wallet validity.

Wallet status types:

The system tracks wallet status using these values:

  • ACTIVE - Valid and ready for use
  • REVOKED - Invalidated by the issuer
  • PENDING - Integrity check in progress
  • ERROR - Failed validation or processing

Attestation during credential issuance​

When a credential issuer requests attestation during OpenID4VCI 1.0 issuance, the wallet obtains them from the wallet provider:

The wallet can request WAAs, WUAs, or both, depending on what the issuer requires. The wallet provider verifies the wallet unit is still active before issuing any attestations.

note

Before requesting a new WUA, the wallet will use an existing non-expired WUA if one is available.

Wallet App Attestation (WAA)​

WAA authenticates the wallet application to credential issuers and verifiers, proving the app is legitimate and unmodified.

Wallet app attestations are used during OAuth authorization flows – specifically in Pushed Authorization Requests (PAR) and Token Requests – before credential issuance begins. These attestations allow issuers to verify that the wallet requesting credentials is:

  • Created by a certified wallet provider
  • Obtained through legitimate distribution channels (official app stores)
  • Unmodified and free from tampering

The attestation follows the OAuth 2.0 Attestation-Based Client Authentication specification and includes information such as the wallet name, wallet link, and wallet provider details.

Attestation lifecycle​

WAAs are short-lived and single-use. Wallets request a new attestation each time one is needed for an authorization flow and use it immediately. The system issues these attestations with a configurable expiration time.

App integrity verification​

The system can optionally verify app integrity before issuing attestations using platform-specific mechanisms:

  • iOS: App Attest validates that the app was distributed through the Apple App store and matches expected bundle identifiers.
  • Android: Key attestation validates app integrity and the use of a genuine Android device.

When integrity verification is enabled, the system validates certificate chains against trusted platform certificate authorities and confirms app bundle identifiers match configured values. If integrity verification is disabled, attestations are issued without these platform-specific checks.

Organizational wallets​

For server-based wallets that don't run on mobile platforms, the system records the operating system as WEB and issues attestations without platform-specific validation checks.

Wallet Unit Attestation (WUA)​

WUAs are used during credential requests when binding credentials to cryptographic keys. These attestations allow issuers to verify that the keys to which credentials will be bound have specific security properties, including:

  • Secure key storage (hardware-backed or software-based)
  • Resistance to key extraction and duplication
  • Required user authentication methods for key operation
  • Compliance with specific security levels or standards

A wallet unit attestation can attest to multiple keys simultaneously. The attestation is provided to the issuer as part of the credential request proof, either with proof of possession of the attested keys or as standalone key attestation without proof of possession.

Attestation lifecycle​

Wallet unit attestations are longer-lived than wallet app attestations (based on recommendations from the ARF) with configurable expiration times. Wallets request new attestations as needed when their current attestation expires or when generating new keys that need to be attested.

Wallet unit revocation​

When a wallet unit is revoked:

Future attestations: All requests for new attestations—both wallet app attestations and wallet unit attestations—are immediately denied.

Existing attestations: The impact depends on whether Token Status List is enabled:

  • Enabled: All previously-issued attestations are immediately invalidated
  • Disabled: Previously-issued attestations remain valid until expiration