Skip to main content

Wallet and Holder Integration

A wallet or holder service is the holder-facing trust boundary for receiving, protecting, understanding, and presenting credentials. It should support individual control without placing the entire security and recovery burden on the individual.

Wallet responsibilities​

A conforming integration should provide clear controls for:

  • receiving credentials from recognized issuance flows;
  • showing issuer, credential type, validity, and status information;
  • protecting credential and holder key material;
  • reviewing requests before presentation;
  • selecting only the claims required for the transaction;
  • creating fresh, audience-bound presentations;
  • managing devices and sessions;
  • supporting backup, continuity, and guarded recovery;
  • exporting or migrating supported credentials where policy permits;
  • communicating failures and lifecycle changes understandably.

The wallet should not silently disclose unrelated credentials, complete wallet inventories, or stable identifiers across unrelated relying parties.

Credential receipt​

During issuance, the wallet should validate enough context to protect the holder:

  1. identify the issuer and credential being offered;
  2. confirm the issuance transaction is current and intended for the wallet interaction;
  3. display the material terms and requested holder action;
  4. prove required holder key control without exposing private material;
  5. receive and validate the credential format;
  6. store the credential in the approved protected container;
  7. confirm the delivery result without revealing unrelated wallet state.

A wallet can check technical consistency, but it does not replace the issuer's responsibility for claim truth or the verifier's later trust policy.

Protected custody​

Wallet security should distinguish:

  • credential payloads;
  • holder keys and binding material;
  • application session state;
  • device registration state;
  • recovery material;
  • indexes and user-visible metadata;
  • backups and synchronized encrypted state.

These elements may require different protection, retention, migration, and deletion controls. Public documentation describes the protection model but not the exact storage envelope, derivation parameters, recovery shares, or device secrets.

Before presentation, the holder should be able to understand:

  • which organization is requesting evidence;
  • the declared purpose;
  • which credential or evidence type is acceptable;
  • which claims will be disclosed;
  • whether a fresh holder proof is required;
  • how long the request remains valid;
  • whether the relying party intends to retain a receipt;
  • how to cancel or decline.

Consent should be specific to the transaction. A previous presentation should not become standing permission for unrelated future requests.

Presentation creation​

A wallet presentation flow should:

  1. authenticate the request and relying context;
  2. match the request against supported credentials;
  3. apply wallet and holder policy;
  4. obtain informed holder authorization;
  5. create only the required disclosures;
  6. bind the response to audience, nonce, transaction, and time;
  7. add holder proof where the credential profile requires it;
  8. transmit through an approved protected channel;
  9. show the holder a clear outcome.

The wallet should not decide whether the relying party ultimately grants access, eligibility, onboarding, or another institutional outcome.

Device lifecycle​

Multi-device continuity requires explicit device states. An integration may need to support:

  • enrollment of a new approved device;
  • step-up verification for sensitive registration;
  • visibility of registered devices;
  • revocation of a lost or compromised device;
  • transfer or synchronization of encrypted state;
  • separation of active, pending, suspended, and retired devices;
  • evidence of device lifecycle events.

A new device should not automatically receive every credential or recovery capability merely because the user authenticated once.

Authentication and sessions​

Wallet access may use passkeys, approved biometrics, device binding, or other policy-controlled methods. Authentication establishes access to the wallet session; it does not by itself prove that every credential is valid or authorize every presentation.

High-impact operations can require step-up authentication, fresh user presence, or additional policy approval. Fallback methods should be bounded, short-lived, and more constrained than ordinary access.

Backup, continuity, and recovery​

Holder control is not practical if one lost device causes permanent exclusion. Continuity should therefore be designed before launch.

A guarded recovery process should separate:

  • request and initiation;
  • identity and device assurance;
  • authorization;
  • preparation of protected recovery material;
  • threshold or custodian release;
  • restoration to an approved device;
  • immediate rotation and invalidation of prior access;
  • evidence and user notification.

No single application, support operator, or custodian should possess a universal recovery secret for the holder.

Portability and interoperability​

A wallet should support approved standards and profiles so that credentials are not confined to one proprietary application. Portability remains subject to credential format, issuer policy, holder binding, status, and the capabilities of the receiving wallet.

Export should not expose private keys or bypass the assurance rules of the credential profile. Migration may require re-binding, reissuance, or a controlled transfer rather than raw file copying.

Accessibility and informed control​

Holder control requires usable choices. Wallet flows should account for:

  • clear non-technical language;
  • multilingual presentation where required;
  • accessible consent and recovery paths;
  • alternatives when biometric processing is not appropriate;
  • safe handling of interrupted or abandoned flows;
  • understandable status and error messages;
  • support processes that do not bypass security policy.

Wallet readiness checklist​

Before production approval, confirm that:

  • credential receipt and presentation profiles are pinned;
  • private material remains under approved holder protection;
  • request authenticity and transaction binding are enforced;
  • the holder can inspect and limit disclosures;
  • device enrollment and revocation are operational;
  • recovery restores control without a universal administrator secret;
  • portability behavior is documented accurately;
  • accessibility and non-biometric alternatives are considered;
  • lost-device, replay, compromised-session, and failed-recovery tests pass;
  • support cannot silently override holder consent or key protection.

Public documentation boundary​

This page does not publish storage-envelope formats, key-derivation parameters, device secrets, recovery-share allocation, synchronization topology, biometric thresholds, session tokens, or production wallet configuration.

See UbID Wallet, Authentication and Device Security, and Recovery and Continuity.