Digital Credentials

W3C First Public Working Draft

More details about this document
This version:
https://www.w3.org/TR/2025/WD-digital-credentials-20250701/
Latest published version:
https://www.w3.org/TR/digital-credentials/
Latest editor's draft:
https://w3c-fedid.github.io/digital-credentials/
History:
https://www.w3.org/standards/history/digital-credentials/
Commit history
Editors:
Marcos Caceres (Apple Inc.)
Tim Cappalli (Okta)
Mohamed Amir Yosef (Google Inc.)
Former editor:
Sam Goto (Google Inc.) - Until
Feedback:
GitHub w3c-fedid/digital-credentials (pull requests, new issue, open issues)

Abstract

This document specifies an API to enable user agents to mediate presentation and issuance of digital credentials such as a driver's license, government-issued identification card, and/or other types of digital credential. The API builds on Credential Management Level 1 as a means by which to request or issue a digital credential from a user agent or underlying platform.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index at https://www.w3.org/TR/.

This is an unofficial proposal.

This document was published by the Federated Identity Working Group as a First Public Working Draft using the Recommendation track.

Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 03 November 2023 W3C Process Document.

1. Introduction

This document defines an API enabling a website to request presentation and issuance of a digital credential.

The API design is agnostic to both credential presentation exchange protocols, credential issuance protocols and credential formats. However, to promote interoperability this document includes a 7. Registry of protocols.

The API is designed to support the following goals:

Digital credentials of many types can be presented and issued using this API. Examples of these types include:

2. Model

Note: Definitions under discussion

The goal of the definitions in this section is to reuse or establish terminology that is common across a variety of digital credential formats and protocols. Discussions surrounding these definitions are active and the definitions are likely to change over the next several months.

Digital credential
A cryptographically signed digital document containing one or more claims made by an issuer about one or more subjects.
Note: Focus on digital credentials about people

This specification is currently focused on digital credentials pertaining to people.

Exchange protocol
A standardized protocol used for exchanging a digital credential between a holder and a verifier. A protocol is identified by a protocol identifier. See section also 7. Registry of protocols.
Issuance protocol
A standardized protocol used for communication between an issuer and a holder during the issuance of a digital credential. The issuance protocol is identified by a protocol identifier. See also section 7. Registry of protocols.
Issuance request
An issuance request is a request to issue a digital credential composed of some issuance request data and an issuance protocol.
issuance request data
A data structure that an issuer or a user agent, via an issuance protocol, to request the issuance of a digital credential by an issuer.
Issuance response
A format that holder uses, via an issuance protocol, to respond to an issuance request by an issuer.
Presentation request
A presentation request is a request for a digital credential composed of request data and a exchange protocol.
Presentation response
A format that a holder's software, such as a digital wallet, uses, via an exchange protocol, to respond to a presentation request by a verifier.
Protocol identifier
A string composed of one or more ASCII lower alpha code points, zero or more U+002D HYPHEN-MINUS code points, and zero or more ASCII digit code points (in any order). For example, "123a-protocol", "abc", or simply "a".
request data
A format that verifier software or a user agent uses, via an exchange protocol, to request a digital credential from a holder.

3. Scope

The following items are within the scope of this specification:

The following items are out of scope:

4. The Digital Credentials API

The Digital Credentials API leverages the Credential Management Level 1 specificaion, allowing user agents to mediate the issuance and presentation of digital credentials.

The API allows requesting a digital credential from the user agent, which in turn presents a credential chooser to the user, allowing them to select a digital credential that can fulfill the request. This is done by the website calling the navigator.credentials.get() method, which runs the request a credential algorithm of Credential Management Level 1. That algorithm then calls back into this specification's DigitalCredential interface's [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method.

Additionally, the API also allows requesting issuance of a digital credential, which initiates an mediated issuance flow between the user agent and/or a holder. This is done by calling the navigator.credentials.create() method, which runs the create a credential algorithm of Credential Management Level 1. That algorithm then calls back into this specification's DigitalCredential interface's [[Create]](origin, options, sameOriginWithAncestors) internal method.

Please see 5. Integration with Credential Management API for complete details of how to integrate with the Credential Management Level 1 specification.

Simliarly, when a site needs to issue a digital credential, the Digital Credentials API mediates the issuance of a digital credential between the site, the user agent, and the holder.

4.1 Extensions to CredentialRequestOptions dictionary

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

4.1.1 The digital member

The digital member allows for options to configure the request for a digital credential.

4.2 The DigitalCredentialRequestOptions dictionary

WebIDLdictionary DigitalCredentialRequestOptions {
  sequence<DigitalCredentialGetRequest> requests;
};

4.2.1 The requests member

The requests specify an exchange protocol and request data, which the user agent MAY match against a holder's software, such as a digital wallet.

4.3 The DigitalCredentialGetRequest dictionary

The DigitalCredentialGetRequest dictionary represents a presentation request. It is used to specify an exchange protocol and some request data, which the user agent MAY match against software used by a holder, such as a digital wallet.

WebIDLdictionary DigitalCredentialGetRequest {
  required DOMString protocol;
  required object data;
};

4.3.1 The protocol member

The protocol member denotes the exchange protocol.

The protocol member's value can be one of the well-defined protocol identifiers defined in 7. Registry of protocols or a custom protocol identifier.

4.3.2 The data member

The data member is the request data to be handled by the holder's credential provider, such as a digital identity wallet.

4.4 Extensions to CredentialCreationOptions dictionary

WebIDLpartial dictionary CredentialCreationOptions {
  DigitalCredentialCreationOptions digital;
};

4.4.1 The digital member

The digital member allows for options to configure the issuance of a digital credential.

4.5 The DigitalCredentialCreationOptions dictionary

WebIDLdictionary DigitalCredentialCreationOptions {
  sequence<DigitalCredentialCreateRequest> requests;
};

4.5.1 The requests member

The requests specify an issuance protocol and request data, which the user agent MAY forward to a holder.

4.6 The DigitalCredentialCreateRequest dictionary

The DigitalCredentialCreateRequest dictionary represents an issuance request. It is used to specify an issuance protocol and some request data, to communicate the issuance request between the issuer and the holder.

WebIDLdictionary DigitalCredentialCreateRequest {
  required DOMString protocol;
  required object data;
};

4.6.1 The protocol member

The protocol member denotes the issuance protocol.

The protocol member's value is be one of the well-defined keys defined in 7. Registry of protocols or any other custom one.

4.6.2 The data member

The data member is the request data to be handled by the holder's credential provider, such as a digital identity wallet.

4.7 The DigitalCredential interface

The DigitalCredential interface represents a conceptual digital credential.

User mediation is always "required". Requesting a DigitalCredential credential does not support "conditional", "optional", or "silent" user mediation. If get() is called with anything other than "required", a TypeError will be thrown.

WebIDL[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
  readonly attribute DOMString protocol;
  [SameObject] readonly attribute object data;
  static boolean userAgentAllowsProtocol(DOMString protocol);
};

DigitalCredential instances are origin bound.

4.7.1 The protocol member

The protocol member is the exchange protocol that was used to request the digital credential, or the issuance protocol that was used to issue the digital credential.

4.7.2 The data member

The data member is the credential's response data. It contains the subset of JSON-parseable object types.

4.7.3 The userAgentAllowsProtocol() method

The userAgentAllowsProtocol() method allows digital credential verifiers to determine which exchange protocols and issuance protocols the user agent allows.

Note

This method does not convey exchange protocol or issuance protocol support in the underlying OS/platform.

User agents MUST NOT vary the response value based on any information about availability of hardware, presence or configuration of software, wallets, credential providers, or digital credentials, or user configuration or preferences. If the response value varied, the user agent would introduce risks both of fingerprinting and of silently revealing other details about user behavior or configuration. The response value SHOULD vary only by user agent major version and indicate whether the browser supports distributing requests with that protocol to underlying platform or provider.

When this method is invoked, the user agent MUST execute the following algorithm:

  1. If protocol is not a protocol identifier, return false.
  2. Return true if the user agent allows protocol, otherwise return false.

5. Integration with Credential Management API

Issue 65: Credential Management integration spec

The CM spec's Extensions points outlines the following things to do to integrate. Adding as a todo list:

This document provides a generic, high-level API that’s meant to be extended with specific types of credentials that serve specific authentication needs. Doing so is, hopefully, straightforward.

For any such extension, we recommend getting in touch with [public-webappsec@](mailto:public-webappsec@w3.org) for consultation and review.

5.1 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method

When invoked, the [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method MUST:

  1. Let global be this's relevant global object.
  2. Let document be global's associated Document.
  3. If document is not a fully active descendant of a top-level traversable with user attention, throw "NotAllowedError" DOMException.
  4. If window does not have transient activation, throw "NotAllowedError" DOMException.
  5. Consume user activation of window.
  6. Let requests be options's digital's requests member.
  7. If requests is empty, throw a TypeError.
  8. Issue
  9. Return a DigitalCredential.

5.2 [[Store]](credential, sameOriginWithAncestors) internal method

When invoked, the [[Store]](credential, sameOriginWithAncestors) MUST call the default implementation of Credential's [[Store]](credential, sameOriginWithAncestors) internal method with the same arguments.

5.3 [[Create]](origin, options, sameOriginWithAncestors) internal method

When invoked, the [[Create]](origin, options, sameOriginWithAncestors) internal method, if the user agent doesn't support issuance, call the default implementation of Credential's [[Create]](origin, options, sameOriginWithAncestors) internal method with the same arguments. Otherwise:

  1. Let global be this's relevant global object.
  2. Let document be global's associated Document.
  3. If document is not a fully active descendant of a top-level traversable with user attention, throw "NotAllowedError" DOMException.
  4. If window does not have transient activation, throw "NotAllowedError" DOMException.
  5. Consume user activation of window.
  6. Let requests be options's digital's requests member.
  7. If requests is empty, throw a TypeError.
  8. Issue
  9. Return a newly constructed DigitalCredential with protocol initialized to the protocol that was used to issue this credential, and data initialized to an issuance response defined by that issuance protocol.

5.4 [[type]] internal slot

The DigitalCredential interface object has an internal slot named [[type]] whose value is "digital".

5.5 [[discovery]] internal slot

The DigitalCredential interface object has an internal slot named [[discovery]] whose value is "remote".

5.6 User permission

This section is non-normative.

The Digital Credential API is a powerful feature that requires express permission from an end-user. This requirement is normatively enforced when calling CredentialsContainer's get() method.

6. Permissions Policy integration

This specification defines a policy-controlled feature identified by the string "digital-credentials-get". Its default allowlist is 'self'.

7. Registry of protocols

Initiating the registration a protocol is done by filing an issue in our GitHub repository.

The following is the registry of exchange protocols and issuance protocols that are supported by this specification.

Note: Official Registry

It is expected that this registry will be become a W3C registry in the future.

7.1 General inclusion criteria

Note

To be included in the registry, the exchange protocol:

  1. MUST be standardized at a consortium the W3C liaises with
  2. MUST be defined in a specification which is freely and publicly available at the stable URL listed in the registry.
  3. MUST define a representation, as either a [WebIDL] dictionary or a JSON object, of the exchange protocol request structure (i.e., the dictionary which defines the semantics and validation of the DigitalCredentialGetRequest's data member) and the issuance protocol request structure (i.e., the dictionary which defines the semantics and validation of the DigitalCredentialCreateRequest's data member).
  4. MUST define a representation, as either a [WebIDL] dictionary or a JSON object, of the exchange protocol response structure (i.e., the dictionary which defines the semantics and validation of the DigitalCredential's data member.
  5. MUST define validation rules for members of the request and response structures.
  6. MUST have undergone privacy review by the W3C's Privacy Working Group and Federated Identity Working Group.
    Note: Organizing reviews
  7. MUST have undergone security review by the Security Interest Group.
  8. MUST have implementation commitment from at least one browser engine, one credential provider/wallet, and one issuer or verifier (depending on the protocol type). Each component MUST be from independent organizations.
  9. MUST have formally recorded consensus by the Federated Identity Working Group to be included in the registry.

7.1.1 Presentation-specific inclusion criteria

To be included as a presentation protocol in the registry (used with navigator.credentials.get), the exchange protocol:

  1. MUST support response encryption.
  2. MUST encrypt any response containing personally identifiable information (PII).

7.2 Change process

To add a new exchange protocol to the registry, or to update an existing one:

Define a protocol identifier.
The protocol identifier MUST be a unique string that is not already in use in the registry. The protocol identifier MUST uniquely define the set of required parameters and/or behavior that a digital credential provider implementation needs to support to successfully handle the request. If the set of required parameters or behaviors is updated in a way which would require a digital credential provider to also require an update to remain functional, a new protocol identifier MUST be assigned and be added to the registry.
Specify a protocol type.
The protocol type is either "Presentation" for presentation protocols used with navigator.credentials.get or "Issuance" for issuance protocols used with navigator.credentials.create.
Describe the protocol.
The description MUST be a brief summary of the protocol's purpose and use case.
Provide a link to the specification.
The specification MUST be a stable URL that points to the authoritative source for the protocol, including validation rules.

User agents MUST support the following exchange protocols:

Table of officially registered exchange protocols.
Protocol identifier Type Description Specification
Coming soon...

8. Security Considerations

This section is non-normative.

Issue: Security Considerations section is a work in progress

This section is a work in progress as this document evolves.

The documents listed below outline initial security considerations for Digital Credentials, both broadly and for presentation on the web. Their contents will be integrated into this document gradually.

8.1 Credential Protocols

Issue: Work in progress

Explain that while the API provides security at the browser API level, that security for the underlying credential issuance or presentation protocol is a separate concern and that developers need to understand that layer of the stack to get a total picture of the protections that are in place during any given transaction.

8.2 Cross-device Protocols

Issue: Work in progress

Explain that cross-device issuance or presentation uses a separate protocol that has its own security characteristics.

8.3 Quishing

Issue: Work in progress

Explain that the API is designed to avoid the problem of quishing (phishing via QR Codes) and other QR Code and non-browser API-based attacks and to be aware of exposure of QR Codes during digital credential interactions.

8.4 Data Integrity

Issue: Work in progress

Explain that the API does not provide data integrity on the digital credential requests or responses and that responsibility is up to the underlying protocol used for the request or response.

8.5 Authentication

Issue: Work in progress

Explain that authentication (such as a PIN code to unlock) to a particular app, such as a digital wallet, that responds to an API request is crucial in high-risk use cases.

8.6 Cross-Site Scripting (XSS) and Cross-Site Request Forgery (CSRF)

Issue: Work in progress

Explain what attacks are possible via XSS and CSRF, if any.

8.7 Session Security

Issue: Work in progress

Explain that once a secure session is established at a website using credentials exchanged over this API, that the subsequent security is no longer a function of the credential used or this API and is up to the session management utilized on the website.

9. Privacy Considerations

This section is non-normative.

Issue: Privacy Considerations section is a work in progress

This section is a work in progress as this document evolves.

The Digital Credentials API integrates into a complex ecosystem with multiple technology layers and various participants (including but not limited to Verifiers, Holders and Issuers), each of which have to consider different aspects of user privacy. This specification does not attempt to exhaustively list all considerations for the different participants. We would like to refer these parties to a variety of other resources that explore the digital credentials threat model more holistically:

Instead, these considerations focus on the Digital Credentials API itself, and describe how user agents can satisfy their user agent duties in an implementation of the API, taking into account the relevant privacy properties of the ecosystem it interacts with.

The privacy considerations for digital credentials are not static. They will evolve over time as the ecosystem matures, and may be informed by the behavior of other actors in the ecosystem, improvements in other layers of the stack, new threats to user privacy, as well as changing societal norms and regulations.

It is expected that the various groups involved in the design and implementation of the Digital Credentials API actively monitor the evolving privacy landscape and participate in the corresponding evolution of the API.

9.1 Design Considerations and Alternatives

The Digital Credentials API is designed to mediate requests for digital credentials from websites, being agnostic to the credential format and the information contained in it, as well as the protocol used to exchange it (within the bounds on the protocol registry inclusion criteria). This and other key design choices are derived from the goal of providing a more secure and private credential exchange experience for users than the existing alternatives (e.g., [custom-schemes]), that is still compatible with common exchange protocols for ease of adoption.

The API provides the connection interface between verifiers and holders, i.e. the means by which a credential exchange protocol is initiated and the user switches to the holder application to select a credential. Solutions that have been used for this purpose in the past include QR codes and custom URL schemes. As documented in Presenting Credentials on the Web and Concerns with custom schemes for identity presentment, those solutions have security, privacy, and accessibility concerns.

With adoption of digital credential technology being driven by ecosystem demand and regulatory mandates, the Web platform offers an alternative to the aforementioned less-desirable technologies that is easy to use for developers, is compatible with existing credential exchange protocols and, most importantly, has better user privacy, security, and accessibility properties than these alternatives.

The Digital Credentials API offers the user agent the ability to intermediate on behalf of the user (e.g. in the form of a credential chooser) to contextualize requests and prevent immediate exposure to holder applications. It also enforces certain minimum requirements on supported protocols, such as response encryption.

Note

9.2 Spectrum of Privacy

The Digital Credentials API serves a variety of use cases with different grades of data disclosure and individual users with different preferences depending on the context that they are in. Notably, the privacy properties of a credential exchange mediated by this API could be mandated by the legal and regulatory environment of an individual user.

This means that some users may not want, or be allowed, to use the most privacy-preserving means of exchanging credential information. Nonetheless, user agents need to serve users with an experience that is private by default and protect them from harm.

Because of this spectrum of preferences and use cases, it may be difficult for a user agent to discern whether a user means to expose their personal information or is being tricked into doing so. It is thus the user agent's responsibility to ensure that every user understands what data they are sharing and who will participate in the exchange of information, before the exchange begins.

9.3 Exchange Protocol and Credential Format

Because the Digital Credentials API sits at the center of an exchange that involves multiple independent parties, the exchange protocol and credential format used by these parties for exchanging user information are crucial to the user agent's goal of protecting user privacy.

The protocol registry for the Digital Credentials API is designed to ensure that, among other requirements, supported protocols facilitate specific privacy-enhancing capabilities. Protocols are required to undergo privacy review by the W3C's Privacy Working Group.

9.3.1 Exchange Protocol Considerations for User Privacy

There are two requirements for protocols that I think need further elaboration:

MUST have undergone privacy review [...]

And

MUST have undergone security review [...]

Technically, a review saying "this protocol is awful in every way" satisfies these criteria.

It would be more useful if there were a set of concrete privacy and security requirements that a protocol needed to satisfy, such a review would be able to say whether a standard was achieved or not. It might be the case that there are subjective elements to a review, but there should also be a minimum bar that each protocol needs to clear.

This goes beyond the present set of requirements in the current inclusion criteria. I don't have a comprehensive list to hand, but one should be possible to develop. And once developed, that list should be in the spec. For instance, does the protocol depend on phoning home? Does the protocol (or the formats it conveys) guarantee unlinkability of presentations? Or - given that unlinkability doesn't make sense for some use cases - under what conditions does the API require the protocol provide unlinkability? What sort of transparency affordances does the protocol include? What sorts of covert channels are acceptable?

9.3.1.1 Selective disclosure

Selective disclosure is a fundamental technique for data minimization that allows holders to share the minimum required information that is requested by a verifier. Protocols are expected to facilitate selective disclosure by allowing the verifier to specify the exact claims needed.

9.3.1.2 Unlinkable presentations

Unlinkability is a property that ensures that, if a user presents attributes from a credential multiple times, verifiers cannot link these separate presentations to conclude they concern the same user (verifier-verifier linkability), or that verifiers can not collude with issuers to report the exchange of a credential from a wallet to the issuer (verifier-issuer linkability). The former is a property that can be maintained by the wallet and issuer, e.g. through issuing fresh credentials for individual verifiers.

While the latter is achievable, e.g. through Zero-Knowledge Proofs, design choices of the API such as encrypted responses make it impossible for a user agent to prove that verifier-issuer unlinkability was achieved in practice. Nonetheless, protocols are requested to limit linkability wherever possible.

Note that unlinkability is exclusively a consideration for attributes that can not be linked to a specific user identity. Inherently linkable attributes such as names, driver's license numbers or phone numbers do not benefit from unlinkability.

Through the Digital Credentials API, the user agent can help verifiers and wallets exchange unlinkable attributes, but, because of response encryption, it can not guarantee that no linkable information is passed between verifiers and wallets. It is recommended that user agents account for this fact in their user permission experience.

Issue 279: Linkability and issuer involvement as a protocol requirement privacy-tracker

Which level of unlinkability is the goal for this API? Can we normatively enforce support for any particular unlinkability features as part of the protocol registry inclusion criteria?

9.3.1.3 "Phone home" mechanisms

"Phoning home" refers to scenarios where the presentation or verification of a digital credential causes a notification or communication back to the issuer or another central entity, which can lead to tracking and profiling of individuals.

Similar to unlinkability, it is impossible for user agents to ensure that an issuer isn't actively involved in the creation or validation of credential presentations after a user has given permission to proceed with a credential request. From that point on, the wallet application owns this decision. While some wallets can be considered user agents, it is generally recommended that the user agent implementing the Digital Credentials API designs its permission experience to prevent exposure of a request to the wallet application before user confirmation (keeping in mind considerations for integrating multiple cooperating user agents).

Protocols are required to support mechanisms that allow issuers, wallets and verifiers avoid or reduce the dependence on "phone home" mechanisms.

Issue 279: Linkability and issuer involvement as a protocol requirement privacy-tracker

Which level of unlinkability is the goal for this API? To what degree can the spec mandate restrictions to issuer involvement?

9.3.1.4 Unlinkable revocation

A common instance of issuer involvement in a credential exchange is for credential revocation checks. This is particularly challenging when presentations are intended to be verifier-issuer unlinkable. When credential presentations are made unlinkable through the use of e.g. Zero-Knowledge Proofs, the credential formats used in protocols are expected to support offline revocation methods such as Cryptographic Accumulators. It is further expected that protocol design and specification discourages the involvement of verifiers for the purpose of revocation where possible.

Issue 280: Can we require protocols to support unlinkable revocation? privacy-tracker

We should discuss whether unlinkable revocation techniques are practical enough to be required normatively.

9.3.1.6 Support for verifier authorization

Verifier authorization refers to the process by which a verifier proves its identity and demonstrates that it is legitimately entitled to request specific attributes or credentials. This is particularly useful when exchanging sensitive data, such as from government-issued credentials. Verifier authorization can limit unnecessary or abusive credential requests, and ensure that a verifier's access is restricted to the specific credential attributes it registered for.

Checking verifier authorization is usually handled by the wallet, but user agents could find the presence of such a scheme helpful in preventing API abuse and designing a well-informed user permission experience.

Issue 281: User agents that only support authorized verifiers (for government credentials) privacy-tracker

Should we require protocols to include provisions that allow user agents to understand verifier authorization?

9.3.1.7 Encrypting credential responses

To prevent exposure of user information to other parties in "transit", for example browser extensions loaded on verifier pages, and to encourage secure storage of user credentials by the verifier, protocols are required to support and mandate encrypted responses in a credential exchange.

Issue 109: Should response encryption be required discussionprivacy-tracker

Related to #49 and several other discussions we've had: do we want to say that the response must always be encrypted (and if so, by which algorithms), or are we OK leaving that as optional?

9.4 Unnecessary Requests for Credentials

Unnecessary credential requests are a key privacy risk to the entire digital credentials ecosystem. They could manifest in different ways and from different motivations:

One challenge here is determining what constitutes "valid" purposes and which requests are therefore "unnecessary", and requires participation from all parties involved in the credential exchange.

For a more detailed exploration of how to determine and address unnecessary usage, it makes sense to consider goverment-issued credentials and other credentials separately, as they potentially differ in the sensitivity of their data and the potential harms from misuse as well as legal & regulatory considerations.

A key component of risk mitigation and ensuring user control that applies to both types of credentials is the user agent's ability to inspect the credential request metadata and make decisions or UI presentation based on it. The DC API ensures this user agent access to the exchange through requirements placed on protocols to transmit requests unencrypted and to include relevant information.

9.4.1 Government-issued credentials

Government-issued digital credentials include travel documents, personal licenses, proof of welfare and public health programs, vehicle registrations, and other documents issued by government authorities, or other documents representing this information. These documents are highly sensitive, as they can contain permanent, irrevocable, unique identifiers that are central to a person's individual identity and ability to interact with vital public services.

9.4.1.1 Risk of theft and leakage of government credentials

The high value of these credentials to users and attackers means there is a significant risk of theft, and significant potential harm from leakage to unauthorized third parties. This includes the request of government identity for the purpose of tracking and personalization.

9.4.1.2 Risk of proliferation of requests for government credentials

A major concern with increased availability of government credentials online is Jevon's Paradox, i.e., the chance of increasing demand for credentials through lower friction of access. This effect is not inherently caused by the Digital Credentials API, and rather the overall increasing adoption of digital credentials across the ecosystem, which, however, would likely see additional momentum from user agent implementation of the Digital Credentials API. As such, the effect needs to be considered by user agents implementing the API, as it might result in harmful outcomes for users:

  • Increased risk of information leakage, and ultimately a less trusted user experience on the Web. When a large number of services access and store government-issued credentials in an insecure manner (i.e. not maintaining encryption or failing to safeguard private keys), the chance of data leaks and unauthorized access increases as well. Even seemingly non-identifying information like birthdates and postal codes, when combined, can statistically identify an individual.
  • Prompt fatigue and a loss in trust by users when they are prompted by a large number of websites to share personal information.
  • Increased potential for surveillance and restrictions on pseudonymous use of online services. Collusion between verifiers and issuers, or other parties, might result in the ability to closely monitor a user's activity on the Web and take adverse action against this individual. Even when no action is taken, the possibility of surveillance alone can cause anxiety, discomfort, and behavioral changes such as inhibition and self-censorship, impacting individual autonomy and freedom of expression.
  • Exclusion and discrimination of individuals who cannot, or do not want to, provide these credentials, prohibiting them from participation in services that would previously not require government-issued credentials, such as forums and social media platforms on the Web.
9.4.1.3 Mitigating unnecessary requests for government credentials

The outlined risks of government-issued digital credentials present a challenge that cannot be solved by a single participant in the ecosystem, and will require a broader policy discussion within individual soverign nations about the risks and benefits of accessing online services through real-world credentials.

It is desirable that a government that issues digital credentials also enact laws and regulations that clearly define how and for what purposes those credentials are able to be used. All parties involved in the exchange, whether they are legally obliged to do so or not, are advised to support any government verifier authentication schemes, if they exist. The support for (and integration of) verifier authentication schemes such as EUDI access and registration certificates can mitigate risks of proliferation of unnecessary credential requests. However, the presence of such schemes is not guaranteed, which significantly increases the risk in a credential exchange.

There are other practical steps that user agents implementing the Digital Credentials API can take to reduce risk, increase user understanding, and prevent certain types of harm:

  • Only support protocols that support selective disclosure and other techniques of data minimization can reduce the impact and likelihood of information leakage, and provide better context to users in permission and consent flows.
  • Support for protocols that allow unlinkability mechanisms such as Zero-Knowledge Proofs can prevent verifier-based surveillance and potential discrimination, by hiding the issuer.
  • Offering useful context and a clearly understandable permission flow will help users make better decisions on whether or not to accept a credential exchange, which can reduce the viability of exchange requests that are made without a concrete user need.

It is further critical that user agents design a permission experience that accounts for the lack of these mitigations, e.g., the exchange of personal information from government credentials without any verifier authentication scheme. It is recommended that a higher level of friction and clear user messaging that highlights the involved risk be applied to these types of exchanges.

9.4.2 Non-government-issued credentials

Non-government-issued credentials include all other digital documents, certificates, and attestations that are not government-issued and don't represent government-issued documents. This could include proof of employment, (non-government) education credentials, or cinema tickets. Notably, their exchange is likely less restricted by laws and regulations. While these documents often don't exhibit the same risks as government-issued credentials, they could also contain identifiable or sensitive information.

9.4.2.1 Risk of theft and leakage of non-government credentials

The impact and viability of credential theft and leakage of non-government credentials is largely based on the content of each individual credential type. In general, it could lead to loss of control and exposure of sensitive private information, as well as impersonation and data theft, which can increase the likelihood of further attacks on the affected individual.

9.4.2.2 Risk of proliferation of requests for government credentials

The flexibility and lack of regulation of non-government credentials carries potential for abuse for the purpose of cross-site tracking and linking identities through long-lived identifiers, such as email address or phone number. Verifiers participating in a tracking scheme based on digital credentials could create user incentives to accept sharing identifier credentials across many sites ("loyalty cards" for the Web), without fully understanding the implications on their privacy.

Even users unwilling to share their information in such a scheme could be affected by prompt fatigue and potentially risk exclusion from using these services.

9.4.2.3 Mitigating unnecessary requests for non-government credentials

For non-government-issued credentials, it is recommended that the user agent understand the requested credential format and its privacy attributes, and build a risk framework that informs the context that is shown to the user, as well as the amount of friction that is appropriate for each credential type. Protocols and formats involved in the exchange of these credentials are generally expected to support features such as selective disclosure and unlinkability, but these features might not always be appropriate or necessary in the exchange of information, especially when it concerns low-risk credentials such as cinema tickets.

A user agent that recognizes the type of credential being requested is encouraged to customize its permission experience to best suit the requested credential and help users understand the consequences of sharing it.

User agents can not be expected to understand all credential requests. A user agent that does not recognize the type of credential being requested is advised to significantly increase user friction in their permission experience, and very clearly communicate the risks of sharing unknown credentials with websites to the user. Note that this could require integration between different user agents to apply appropriate levels of friction and transparency. For example, a browser might delegate knowledge about credential requests to the operating system, which might require wallets to register known credential types and reject an exchange request for an unknown credential type.

Issue 100: Consider applying the robustness principle with regard to user agent request validation discussionprivacy-considerations

The need to provide users with appropriate transparency conflicts with the desire to enable the ecosystem to develop new credential formats without explicit user agent buy-in.

Issue 117: Should we have a common and interoperable definition of request types and their privacy properties? discussionprivacy-tracker

Is it a good idea for the group to maintain a registry of request types and/or credential types?

9.4.2.4 Reporting abuse
Issue 267: reporting abuse of credential requests privacy-trackerprivacy-considerations

Consider an interoperable abuse reporting system for verifiers making unnecessary and abusive requests.

9.5 Fingerprinting and Data Leakage

9.5.1 Browser fingerprinting

While the API ensures that no user data is ever shared without a permission prompt, the longevity and uniqueness of real world identifiers that are likely to be returned by the Digital Credentials API make it a potential target for trackers and fingerprinters.

Even with selective disclosure, attackers might combine data from a digital credential (such as the user's age, or the credential issuer, timestamps, see 9.5.2 Leaking incidental data with credential presentations) to reidentify and/or fingerprint users.

This attack might be harder for third-party attackers (such as scripts embedded on the verifier's pages, but not actively collaborating with them for the purpose of tracking) because response encryption is mandatory and responses should be decrypted on the verifier's server. The verifier could thus ensure not to reflect back decrypted information back to client-side JavaScript. Not all verifiers will choose to do so, however.

9.5.2 Leaking incidental data with credential presentations

To ensure authenticity of a credential, its presentation to verifiers generally includes more information than the content the verifier is requesting access to. It will usually contain at least a signature of the issuer and the wallet, and potentially other metadata.

This additional information could be used to reidentify and fingerprint users, which is especially relevant when an otherwise unlinkable presentation is made.

While the Digital Credentials API does not control the content of a credential response, user agents can help protect users against this type of tracking through clearly highlighting which information likely gets shared with the verifier beyond what was requested, and, more broadly, by identifying and blocking fingerprinting through the API by verifiers.

9.5.3 Revealing device properties through protocol availability

The Digital Credentials API exposes information about which credential exchange protocols are supported by the user agent through userAgentAllowsProtocol(). It mitigates browser fingerprinting and revealing information about the user's device configuration through not customizing its response based on e.g. which wallet applications are installed on a user's device. The returned information is thus, at best, equivalent to a user agent version.

9.5.4 Avoiding leaks of credential availability

The Digital Credentials API does not enable sites to learn whether a credential is available without first going through a user permission flow. Revealing the presence of credentials would be a risk to user privacy, as the presence of a credential is personal information that the user might not have preferred to share with the site, and, in combination with other signals, could be used to identify the user without their permission. It is also a risk to free expression, as websites might increasingly start to demand the presentation of these credentials from the user in order to access services, excluding individuals who are unwilling to present credentials.

9.6 User Permission and Transparency

Issue: Work in progress

The Digital Credentials API enables the sharing of highly personal, sensitive, and at-risk user information with websites via credentials, potentially granting the ability to track users online and offline, through permanent, unique, irrevocable, cross-context identifiers. It also reveals parts of the user's browsing activity as well as their intent to identify to specific websites and/or wallets. One crucial responsibility of the user agent in a credential request is to gather permission from the user to proceed with the exchange of information.

Important context details that are needed for a user to make an informed decision about proceeding with a credential exchange include the following:

It is advised that user agents in their implementation ensure that the details listed are fully disclosed to the user before an exchange of any user-related information occurs.

Issue 252: Should we normatively define elements of a permission prompt? privacy-considerations

Should these be normative in the spec?

Issue 44: API requests should provide the site with what they need to explain why and how requested credential information will be used enhancementdc2-proposalprivacy-tracker

Should the API be designed so the site can provide in-context explanations?

9.6.1 Handling multiple credential requests

Issue 286: Privacy Considerations for multiple presentation requests (and responses) privacy-trackerprivacy-considerations

We need to describe concerns, tradeoffs and possible mitigations of handling multiple requests and responses for credential presentation.

9.6.2 Integrating Multiple User Agents

Depending on the technical architecture of a user's system, it is likely that the definition of a "user agent" will include multiple cooperating layers of the software stack, such as a browser and the operating system. The greatest priority for these layers has to be a safe and well-informed user permission experience. As such, integration can be vital for user safety. Some layers may hold information that is inaccessible by other layers, such as the availability of a user's credentials. Overprompting or prompting without sufficient context could lead to (exploitable) confusion and prompt blindness.

For this reason, user agents prompting for permission are encouraged to integrate software layers for an ideal user experience, if they consider it safe to do so. This could happen, for example, if a browser trusts the API contract of an operating system to show an appropriate prompt, and thus does not show a prompt itself.

9.6.3 Permission Prior to Wallet Selection

As part of the user permission flow, the user agent needs to ensure that users retain the power to choose whether to forward a credential request to a wallet, and which wallet to select. This is due to the information disclosure that happens as part of the request, and the ability of wallets to retain or share this information at the time of the request.

10. Accessibility Considerations

This section is non-normative.

Issue: Work in Progress

This section is a work in progress as this document evolves.

11. IDL Index

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

dictionary DigitalCredentialRequestOptions {
  sequence<DigitalCredentialGetRequest> requests;
};

dictionary DigitalCredentialGetRequest {
  required DOMString protocol;
  required object data;
};

partial dictionary CredentialCreationOptions {
  DigitalCredentialCreationOptions digital;
};

dictionary DigitalCredentialCreationOptions {
  sequence<DigitalCredentialCreateRequest> requests;
};

dictionary DigitalCredentialCreateRequest {
  required DOMString protocol;
  required object data;
};

[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
  readonly attribute DOMString protocol;
  [SameObject] readonly attribute object data;
  static boolean userAgentAllowsProtocol(DOMString protocol);
};

12. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A. References

A.1 Normative references

[credential-management]
Credential Management Level 1. Nina Satragno; Marcos Caceres. W3C. 13 August 2024. W3C Working Draft. URL: https://www.w3.org/TR/credential-management-1/
[fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[permissions-policy]
Permissions Policy. Ian Clelland. W3C. 6 May 2025. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[vc-data-model]
Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[vc-data-model-2.0]
Verifiable Credentials Data Model v2.0. Ivan Herman; Michael Jones; Manu Sporny; Ted Thibodeau Jr; Gabe Cohen. W3C. 15 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model-2.0/
[WebIDL]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

A.2 Informative references

[credential-considerations]
User considerations for credentials on the Web. Nick Doty; Rick Byers. W3C. 2025-03-26. URL: https://github.com/w3c/credential-considerations/blob/main/credentials-considerations.md
[custom-schemes]
Concerns with custom schemes for identity presentment. Rick Byers. W3C. 2024-05-01. URL: https://github.com/w3c-fedid/digital-credentials/blob/main/custom-schemes.md
[design-principles]
Web Platform Design Principles. Martin Thomson; Jeffrey Yasskin. W3C. 26 June 2025. W3C Working Group Note. URL: https://www.w3.org/TR/design-principles/
[identity-web-impact]
Identity & the Web. Simone Onofri. W3C. 2025-02-25. URL: https://www.w3.org/reports/identity-web-impact
[permissions]
Permissions. Marcos Caceres; Mike Taylor. W3C. 24 June 2025. W3C Working Draft. URL: https://www.w3.org/TR/permissions/
[presenting-credentials-on-the-web]
Presenting Credentials on the Web. Simone Onofri. URL: https://docs.google.com/document/d/1Ppaz_EnhzHqPOz5UusRJvbSunh-RXPWgJ3Np_TM2EE0/
[privacy-principles]
Privacy Principles. Robin Berjon; Jeffrey Yasskin. W3C. 15 May 2025. STMT. URL: https://www.w3.org/TR/privacy-principles/
[rfc6973]
Privacy Considerations for Internet Protocols. A. Cooper; H. Tschofenig; B. Aboba; J. Peterson; J. Morris; M. Hansen; R. Smith. IETF. July 2013. Informational. URL: https://www.rfc-editor.org/rfc/rfc6973
[security-privacy-questionnaire]
Self-Review Questionnaire: Security and Privacy. Theresa O'Connor; Peter Snyder; Simone Onofri. W3C. 18 April 2025. W3C Working Group Note. URL: https://www.w3.org/TR/security-privacy-questionnaire/
[threat-model-decentralized-identities]
Threat Model for Decentralized Identities. Simone Onofri. W3C. 2025-05-28. URL: https://github.com/w3c-cg/threat-modeling/blob/main/models/decentralized-identities.md
[w3c-process]
W3C Process Document. Elika J. Etemad (fantasai); Florian Rivoal. W3C. 3 November 2023. URL: https://www.w3.org/policies/process/