Issuing a verifiable credential into a wallet is an OAuth-protected API call that hands a long-lived, portable proof of identity to software the issuer does not control, so mistakes at issuance are copied into every later presentation. OpenID for Verifiable Credential Issuance (OpenID4VCI) 1.0 is the OpenID Foundation standard that defines that API: how an issuer offers credentials, how a wallet obtains authorisation, how keys are proven and attested, and how credentials in SD-JWT VC, ISO mdoc or W3C formats are delivered. This guide explains the flows and endpoints, the security decisions an issuer must make (pre-authorised codes, transaction codes, wallet and key attestation, nonces), how HAIP tightens them, and how to roll out and monitor an issuance service. It is for teams building or procuring credential issuers in government, finance, education and enterprise. The verifier side is covered in the OpenID for Verifiable Presentations (OpenID4VP) Guide and fundamentals in the Verifiable Credentials Guide.
Key takeaways
- It is a Final specification built on OAuth. OpenID4VCI 1.0 was published as Final on 16 September 2025 (an errata set is in progress); the credential issuer is an OAuth resource server, the wallet is an OAuth client, and all OAuth security practice applies.
- Two authorisation paths. The Authorization Code Flow authenticates the user during issuance (PAR and PKCE recommended); the Pre-Authorized Code Flow relies on authentication done earlier and is exposed to code replay and phishing unless protected by a transaction code and trusted issuers.
- Bind credentials to keys, then check the keys. Key proofs (
openid4vci-proof+jwt) with a freshc_nonceprevent replay; key attestations tell the issuer whether those keys live in secure hardware. - Know which wallet you are issuing to. Wallet Attestation, based on OAuth Attestation-Based Client Authentication, lets the issuer authenticate the wallet app instance; HAIP makes it mandatory.
- Several dependencies are still drafts. The specification itself lists pre-final dependencies such as SD-JWT VC, Attestation-Based Client Authentication and Token Status List, and tells implementers to use the referenced versions unless a profile says otherwise.
Roles, endpoints and metadata
| Component | Required? | Purpose | Security notes |
|---|---|---|---|
Credential Issuer metadata at /.well-known/openid-credential-issuer | Yes | Lists credential_configurations_supported, endpoints, authorisation servers, encryption support | May be signed (openidvci-issuer-metadata+jwt, sub = issuer identifier); wallets must establish trust in the signer or reject signed metadata |
| Credential Endpoint | Yes | Issues one or more credentials of one configuration and dataset | Protected by the access token; TLS per BCP 195 |
| Nonce Endpoint | Optional (recommended) | Returns a fresh c_nonce for key proofs | Responses must be uncacheable (no-store) |
| Deferred Credential Endpoint | Optional | Delivers credentials later using transaction_id and polling interval | Bind the transaction to the same wallet and token |
| Notification Endpoint | Optional | Wallet reports credential_accepted, credential_failure or credential_deleted | Useful for life-cycle and support, not a security control |
| Credential Offer | Optional | Issuer-initiated start, by value (credential_offer) or by https reference (credential_offer_uri), often as a QR code or openid-credential-offer:// link | Unauthenticated: wallets must treat it as untrusted input |
| Authorization Server | Yes | Issues access tokens; may protect several issuers | Same hardening as any OAuth server |
OpenID4VCI adds to OAuth a Pre-Authorized Code grant (urn:ietf:params:oauth:grant-type:pre-authorized_code), an openid_credential authorization details type (RFC 9396), the issuer_state parameter that ties an offer to the later authorisation request, and the wallet client metadata credential_offer_endpoint.
Credential formats
| Format identifier | Credential type | Typical use |
|---|---|---|
dc+sd-jwt | IETF SD-JWT VC | Selective disclosure JSON credentials, EU PID and attestations |
mso_mdoc | ISO/IEC 18013-5 mdoc secured by the Mobile Security Object | Mobile driving licences, proximity presentation |
jwt_vc_json | W3C VC signed as JWT, not using JSON-LD | W3C ecosystems without linked data processing |
jwt_vc_json-ld | W3C VC signed as JWT, using JSON-LD | W3C ecosystems with contexts |
ldp_vc | W3C VC secured with Data Integrity proofs | Linked data ecosystems |
Choose formats by what your verifiers can accept, not by issuer convenience. Batch issuance lets one request return several credentials of the same format and dataset, which should differ in cryptographic data (for example each bound to a different key) so presentations cannot be linked. See the SD-JWT and SD-JWT VC Guide.
Choosing a flow: authorisation code or pre-authorised code
| Aspect | Authorization Code Flow | Pre-Authorized Code Flow |
|---|---|---|
| User authentication | At the issuer's authorisation endpoint during issuance | Done earlier, out of band (in a branch, portal or onboarding) |
| Session binding | PKCE binds the code to the wallet session | Not bound by design; the specification says the code is vulnerable to replay, for example by shoulder surfing a QR code |
| Main protections | PAR (recommended), PKCE, issuer_state, client and wallet authentication | Short-lived, single-use code; Transaction Code (tx_code) sent over another channel; attempt limits |
| Phishing exposure | Standard OAuth phishing risks | Transaction code phishing via attacker-run issuers |
| Best for | Online issuance where the user can sign in | Cross-device and in-person issuance, deferred issuance after manual checks |
- Transaction code guessing: codes are short, so the authorisation server should limit failed attempts per pre-authorised code, then invalidate the code and return
invalid_grant; transaction codes should be short-lived and single use. - Transaction code phishing: an attacker can run a fake issuer and trigger a code from another service (for example a payment confirmation) that the user then types into the wallet. The specification recommends wallets interact only with trusted issuers and may show the user the endpoint the code goes to.
- Offers are untrusted: the wallet must validate the issuer exactly as if the user had started the flow, and must not accept credentials simply because they came through an offer. Wallets should also require user interaction before fetching a
credential_offer_uri, because automatic fetching lets attackers detect which wallet is installed.
For the cross-device risks behind QR-based offers, see the Cross-Device Flow Security Guide.
Key binding, proofs and attestations
- The
jwtproof type: headertypopenid4vci-proof+jwt,algneithernonenor a MAC, exactly one ofkid,jwkorx5c; bodyaud= the Credential Issuer Identifier,iat, andnonce= the server'sc_noncewhenever a Nonce Endpoint exists.isscarries the wallet'sclient_id, except for anonymous pre-authorised access. - Proof replay: the
c_nonceis the main defence against an attacker replaying a captured proof to obtain duplicate credentials; issuers are recommended to use the Nonce Endpoint and decide how long a nonce stays valid. Server-generated nonces containing server time avoid clock skew problems. - Key attestation: a
key-attestation+jwtsigned by the wallet provider or key storage component listsattested_keysand may assertkey_storageanduser_authenticationresistance using ISO/IEC 18045 attack potential levels:iso_18045_high(VAN.5),iso_18045_moderate(VAN.4),iso_18045_enhanced-basic(VAN.3) andiso_18045_basic(VAN.2). It can travel in thekey_attestationheader of ajwtproof, or alone as theattestationproof type, which avoids extra user interaction because the keys need not sign. - Wallet attestation: a JWT following the Attestation-Based Client Authentication Client Attestation format, with optional
wallet_name,wallet_linkandstatus, issued by the wallet provider's backend after checking platform integrity (the specification cites iOS DeviceCheck and Android Play Integrity). It is presented with the PAR and token requests. See the OAuth Attestation-Based Client Authentication Guide. - Split-architecture wallets: when a wallet has a server component, the specification warns that a server acting as trust anchor for attestations cannot also safeguard against itself, and that codes and proofs must not be routed through a server component that is not fully trusted.
| Issuer question | Mechanism | Decision guidance |
|---|---|---|
| Is this request fresh, not replayed? | c_nonce from the Nonce Endpoint | Always use it |
| Does the wallet hold the key the credential will be bound to? | jwt proof | Required for holder-bound credentials |
| Is the key in secure hardware with adequate user authentication? | Key attestation | Require for high-assurance credentials (identity, licences, payment) |
| Is this a genuine, approved wallet app instance? | Wallet attestation or other client authentication | Require where a trust framework approves wallets; mandatory under HAIP |
| Can I withdraw the credential later? | Status reference, for example Token Status List | Required for anything longer-lived than about a day |
The HAIP profile for high assurance
The OpenID4VC High Assurance Interoperability Profile (HAIP) 1.0, Final in December 2025, narrows OpenID4VCI for regulated ecosystems. It requires wallets to use, and issuers to require, OAuth client authentication; wallets to authenticate at the PAR and token endpoints with a Wallet Attestation that is not reused across issuers; support for key attestations; DPoP sender-constrained tokens with handling of DPoP-Nonce; and PKCE with S256, applying FAPI 2.0 provisions with PAR required where the authorisation endpoint is used. If you issue identity documents, start from HAIP and your ecosystem's rulebook rather than base OpenID4VCI. For the EU context see the EUDI Wallet Architecture and Reference Framework Guide and the FAPI 2.0 Security Profile Implementation Guide.
Worked example: issuance after an in-person check
A licensing authority verifies an applicant at a counter and wants to issue an mdoc and an SD-JWT VC to the applicant's wallet.
- Offer: the clerk's system creates an offer with
credential_issuer,credential_configuration_idsfor both formats, and a pre-authorised code grant with atx_codeobject (numeric, length 6, description "code sent by text message"). It is shown as a QR code at the counter and expires in minutes. - Wallet checks: after the applicant taps to accept, the wallet fetches the issuer metadata, verifies the issuer is on its trusted list and shows the issuer name before asking for the code.
- Token request: the wallet sends the pre-authorised code, the transaction code and its Wallet Attestation with proof of possession; the authorisation server checks attempts, invalidates the code on use and issues a DPoP-bound access token.
- Nonce and proofs: the wallet calls the Nonce Endpoint, then requests each credential with proofs for several fresh keys plus a key attestation showing
iso_18045_highkey storage. - Deferred delivery: if a back-office check is still running, the issuer returns
transaction_idandinterval, and the wallet polls the Deferred Credential Endpoint with the same token. - Delivery and status: the issuer returns a batch of credentials, each bound to a different key and each with its own status list index; the wallet sends
credential_acceptedto the Notification Endpoint.
A shoulder-surfer who photographs the QR code gets nothing without the text message code, and after a few wrong guesses the code is invalidated. A replayed proof fails the nonce check, and a cloned app without the attested keys cannot obtain the credentials.
Implementation roadmap
- Define what you issue: credential datasets, formats, validity periods, holder binding requirements and the identity proofing level needed before issuance.
- Pick the trust framework: which wallets you accept (wallet attestation issuers, trust lists), which key storage levels, and how wallets will trust your signed metadata and signing keys.
- Stand up the OAuth layer: authorisation server with PAR, PKCE S256, DPoP and attestation-based client authentication; short-lived, single-use pre-authorised codes with transaction codes and attempt limits.
- Build the issuer endpoints: metadata (signed where your ecosystem expects it), Nonce, Credential, and if needed Deferred and Notification endpoints; enable credential response encryption for sensitive data.
- Add revocation from day one: include status references in every credential that lives longer than your re-issuance cycle. See the Token Status List and Credential Revocation Guide.
- Test with conformance and negative cases: replayed proofs, stale nonces, wrong
aud, reused pre-authorised codes, brute-forced transaction codes, untrusted wallet attestations, and a malicious offer pointing at a look-alike issuer. - Pilot: issue to a limited population and a small set of approved wallets, watch failure reasons, then widen.
- Plan rollback: keep the ability to suspend issuance per credential configuration, revoke a batch through the status list, and rotate signing keys with published metadata updates.
Detection and measurement
- Issuance anomalies: many credentials to one wallet instance or key, repeated failed transaction codes, pre-authorised codes redeemed from unexpected networks or long after the offer.
- Attestation signals: wallet attestations from unknown attesters, revoked wallet versions, key attestations below the required level.
- Phishing indicators: look-alike issuer domains appearing in offers reported by users or wallet providers; offers are a phishing vector (MITRE ATT&CK T1566.002 Spearphishing Link is the closest technique for malicious offer links).
- Life cycle: notification events (
credential_failure,credential_deleted) and time from a revocation decision to status publication.
| Metric | Target |
|---|---|
Credential requests with valid fresh c_nonce proofs | 100% |
| High-assurance credentials issued only to attested keys at the required level | 100% |
| Pre-authorised codes redeemed within lifetime and only once | 100%; reuse attempts alerted |
| Transaction code lockouts per thousand offers | Tracked; spikes investigated |
| Credentials carrying a status reference | All credentials beyond the re-issuance window |
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | IA-12 Identity Proofing; IA-8 Identification and Authentication (Non-organizational Users) | Proofing before issuance; authenticating citizens and customers |
| NIST SP 800-53 Rev. 5 | IA-5 Authenticator Management; SC-13 Cryptographic Protection | Holder key binding, issuer signing keys, key attestation |
| NIST SP 800-53 Rev. 5 | SC-8 Transmission Confidentiality and Integrity; AU-10 Non-repudiation | TLS and response encryption; signed credentials and metadata |
| NIST CSF 2.0 | PR.AA-02 | Identities are proofed and bound to credentials |
| OWASP ASVS 5.0 | V10.4.13, V10.4.10 | PAR and authenticated back-channel requests in the OAuth layer |
| ISO/IEC 27001:2022 Annex A | 5.16 Identity management; 5.17 Authentication information | Issuance and life cycle of identity credentials |
Common failure patterns
- Pre-authorised codes without a transaction code: a QR code on a screen or in an email becomes a bearer credential anyone can redeem.
- Unlimited transaction code attempts: a six-digit numeric code falls quickly to online guessing.
- Skipping the nonce: issuing on proofs with only
iatlets captured proofs be replayed for duplicate credentials. - Trusting any wallet: issuing high-assurance credentials to software keys in unknown apps, where the private key can be copied.
- No revocation plan: long-lived credentials issued without a status reference cannot be withdrawn after fraud or device loss.
- Building on unpinned drafts: mixing dependency versions (for example a newer attestation draft with an older profile) breaks interoperability; follow the versions the specification or your profile names.
Practitioner checklist
- Record the OpenID4VCI version, profile (for example HAIP) and dependency draft versions you implement.
- Publish issuer metadata, signed if your ecosystem requires, and document how wallets trust your keys.
- Use the Authorization Code Flow with PAR and PKCE wherever the user can authenticate online.
- Protect pre-authorised codes with short lifetimes, single use, transaction codes and attempt limits.
- Require
openid4vci-proof+jwtproofs with a freshc_nonceand the correctaud. - Require key attestation and wallet attestation for high-assurance credentials.
- Issue batches with distinct keys for unlinkability, and include a status reference in every long-lived credential.
- Monitor issuance anomalies, attestation failures and revocation latency.
Standards and references
- OpenID Foundation: OpenID for Verifiable Credential Issuance 1.0
- OpenID Foundation: OpenID4VCI specification repository (errata editor's draft)
- OpenID Foundation: OpenID4VC High Assurance Interoperability Profile 1.0
- IETF: OAuth 2.0 Attestation-Based Client Authentication (Internet-Draft)
- IETF: Token Status List (Internet-Draft)
- IETF: RFC 9126 OAuth 2.0 Pushed Authorization Requests
Related NHI Mgmt Group resources: Verifiable Credentials Guide · OpenID for Verifiable Presentations (OpenID4VP) Guide · Digital Identity Wallets Guide · Wallet Unit Attestation and Device-Bound Keys Guide