Skip to main content

Direct Issue into a Wallet

This guide explains how to issue a verifiable credential directly into a Business Wallet, without the holder having to scan a QR code or tap Accept. The credential simply appears in the wallet.

A typical use case is the direct issuance of a credential by a trusted party you have authorized to add credentials to your wallet, for example the Tax Authority. With the Tax Authority registered as a trusted contact, it can deliver new credentials to your Business Wallet as soon as they become available, without any action on your part.

When to use it​

The standard issuance flow is attended: you start an issuance, the holder is redirected to their wallet (or scans a QR code), and they explicitly accept the credential over the OpenID4VCI protocol.

Direct issue is unattended. It is the right choice when:

  • You are provisioning a wallet you control or just created (e.g. during onboarding) and there is no human present to accept a QR code.
  • The issuer and the wallet belong to the same trust domain, and an explicit accept step adds friction without adding value.
  • You want the credential to be present the moment the user first opens their wallet.
Direct issue requires explicit trust

A credential can only be pushed into a wallet unattended if the issuer has first been registered in that wallet as a trusted contact with direct issue allowed. Without that, the credential is accepted and then immediately discarded by the wallet. See Trusted Contacts.

The three building blocks​

Direct issue combines three pieces. Read them in order:

  1. Trusted Contacts: register the issuer's DID in the target wallet and flag it as allowed to issue directly. This is the security gate that makes unattended issuance safe. The owner of the holder wallet can add the trusted contact via the UI or with the Create a trusted contact API.
  2. Issue Directly to a Wallet: the two API calls that create a credential offer and push it into the wallet with directIssue=true.
  3. The Inbox: the attended alternative. When you push an offer without directIssue, it lands in the wallet's inbox for the user to accept later.

How it works end to end​

The direct issue flow (directIssue=true)​

The key difference from the standard flow is step three: instead of redirecting a browser or showing a QR code, you post the credential offer to the holder wallet's OIDC offer endpoint with directIssue=true. The holder wallet then completes the OpenID4VCI exchange against the issuer on the holder's behalf (resolve offer, token endpoint, credential endpoint) and applies the trust check: if the issuer is a trusted contact with direct issue allowed, the credential is created in the wallet; otherwise it is discarded.

Posting the same offer without directIssue=true is the attended path: the offer is not pulled automatically but stored in the holder wallet's inbox for the user to accept later.

The inbox defers the pull

The diagram above shows the directIssue=true flow only. In the inbox path the wallet does not run the OpenID4VCI exchange at offer time. It stores just the credential offer URI and no credential exists yet. The token and credential endpoint calls, and therefore the trust check, are deferred until the user accepts the offer from the inbox.

The inbox flow (directIssue omitted)​

When you post the offer without directIssue=true, the wallet stores the offer and waits. The pull only happens later, when the user accepts the offer from the inbox.

Because the user explicitly accepts, the inbox flow has no automatic trust check: the user is the gate, applied before the pull rather than after it.