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 [=credential type examples|other types of digital credential=]. The API builds on [[[credential-management-1]]] as a means by which to request or issue a digital credential from a user agent or underlying platform.
This is an unofficial proposal.
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 [=digital credential/presentation requests|presentation=] [=digital credential/exchange protocols=], credential [=digital credential/issuance request|issuance=] [=digital credential/issuance protocols|protocols=] and credential formats. However, to promote interoperability this document includes a [[[#protocol-registry]]].
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:
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.
This specification is currently focused on digital credentials pertaining to people.
The following items are within the scope of this specification:
The following items are out of scope:
partial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
The digital member allows for options to configure the request for a [=digital credential=].
dictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialGetRequest> requests;
};
The requests specify an [=digital credential/exchange protocol=] and [=digital credential/request data=], which the user agent MAY match against a holder's software, such as a digital wallet.
The {{DigitalCredentialGetRequest}} dictionary represents a [=digital credential/presentation request=]. It is used to specify an [=digital credential/exchange protocol=] and some [=digital credential/request data=], which the user agent MAY match against software used by a holder, such as a digital wallet.
dictionary DigitalCredentialGetRequest {
required DOMString protocol;
required object data;
};
The protocol member denotes the [=digital credential/exchange protocol=].
The {{DigitalCredentialCreateRequest/protocol}} member's value can be one of the well-defined protocol identifiers defined in [[[#protocol-registry]]] or a custom protocol identifier.
The data member is the [=digital credential/request data=] to be handled by the holder's credential provider, such as a digital identity wallet.
partial dictionary CredentialCreationOptions {
DigitalCredentialCreationOptions digital;
};
The digital member allows for options to configure the issuance of a [=digital credential=].
dictionary DigitalCredentialCreationOptions {
sequence<DigitalCredentialCreateRequest> requests;
};
The requests specify an [=digital credential/issuance protocol=] and [=digital credential/request data=], which the user agent MAY forward to a [=holder=].
The {{DigitalCredentialCreateRequest}} dictionary represents an [=digital credential/issuance request=]. It is used to specify an [=digital credential/issuance protocol=] and some [=digital credential/request data=], to communicate the issuance request between the issuer and the holder.
dictionary DigitalCredentialCreateRequest {
required DOMString protocol;
required object data;
};
The protocol member denotes the [=digital credential/issuance protocol=].
The {{DigitalCredentialCreateRequest/protocol}} member's value is be one of the well-defined keys defined in [[[#protocol-registry]]] or any other custom one.
The data member is the [=digital credential/request data=] to be handled by the holder's credential provider, such as a digital identity wallet.
The DigitalCredential interface represents a conceptual [=digital credential=].
[=User mediation=] is always {{CredentialMediationRequirement/"required"}}. [=Request a credential|Requesting a DigitalCredential credential=] does not support {{CredentialMediationRequirement/"conditional"}}, {{CredentialMediationRequirement/"optional"}}, or {{CredentialMediationRequirement/"silent"}} [=user mediation=]. If {{CredentialsContainer/get()}} is called with anything other than {{CredentialMediationRequirement/"required"}}, a {{TypeError}} will be thrown.
[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
readonly attribute DOMString protocol;
[SameObject] readonly attribute object data;
static boolean userAgentAllowsProtocol(DOMString protocol);
};
{{DigitalCredential}} instances are [=Credential/origin bound=].
The protocol member is the [=digital credential/exchange protocol=] that was used to request the [=digital credential=], or the [=digital credential/issuance protocol=] that was used to issue the [=digital credential=].
The data member is the credential's response data. It contains the subset of JSON-parseable object types.
The {{DigitalCredential/userAgentAllowsProtocol()}} method allows digital credential [=verifiers=] to determine which [=digital credential/exchange protocols=] and [=digital credential/issuance protocols=] the user agent allows.
This method does not convey [=digital credential/exchange protocol=] or [=digital credential/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:
When invoked, the [[\DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method MUST:
When invoked, the [[\Store]](credential, sameOriginWithAncestors) MUST call the default implementation of {{Credential}}'s {{Credential/[[Store]](credential, sameOriginWithAncestors)}} internal method with the same arguments.
When invoked, the [[\Create]](origin, options, sameOriginWithAncestors) internal method, if the user agent doesn't support issuance, call the default implementation of {{Credential}}'s {{Credential/[[Create]](origin,options, sameOriginWithAncestors)}} internal method with the same arguments. Otherwise:
The {{DigitalCredential}} [=interface object=] has an internal slot named [[\type]] whose value is "digital".
The {{DigitalCredential}} [=interface object=] has an internal slot named [[\discovery]] whose value is "remote".
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 {{CredentialsContainer/get()}} method.
This specification defines a [=policy-controlled feature=] identified by the string "digital-credentials-get". Its [=policy-controlled feature/default allowlist=] is [=default allowlist/'self'=].
Initiating the registration a protocol is done by filing an issue in our GitHub repository.
The following is the registry of [=digital credential/exchange protocols=] and [=digital credential/issuance protocols=] that are supported by this specification.
It is expected that this registry will be become a [=W3C registry=] in the future.
To be included in the registry, the [=digital credential/exchange protocol=]:
To be included as a presentation protocol in the registry (used with `navigator.credentials.get`), the [=digital credential/exchange protocol=]:
To add a new [=digital credential/exchange protocol=] to the registry, or to update an existing one:
[=User agents=] MUST support the following [=digital credential/exchange protocols=]:
| [=digital credential/Protocol identifier=] | [=registry/Type=] | [=registry/Description=] | [=registry/link|Specification=] |
|---|---|---|---|
| Coming soon... | |||
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.
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.
Explain that cross-device issuance or presentation uses a separate protocol that has its own security characteristics.
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.
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.
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.
Explain what attacks are possible via XSS and CSRF, if any.
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.
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.
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 [=digital credential/exchange protocol|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 [[[custom-schemes]]], 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.
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.
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.
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.
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.
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?
"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.
Which level of unlinkability is the goal for this API? To what degree can the spec mandate restrictions to issuer involvement?
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.
We should discuss whether unlinkable revocation techniques are practical enough to be required normatively.
User understanding and participation are non-negotiable properties of a credential exchange. The protocol is expected to help all involved parties enable user participation by providing the information vital for informed permission and/or consent.
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.
Should we require protocols to include provisions that allow user agents to understand verifier authorization?
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.
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.
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.
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.
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:
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:
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.
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.
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.
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.
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.
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.
Is it a good idea for the group to maintain a registry of request types and/or credential types?
Consider an interoperable abuse reporting system for verifiers making unnecessary and abusive requests.
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.
Should these be normative in the spec?
Should the API be designed so the site can provide in-context explanations?
We need to describe concerns, tradeoffs and possible mitigations of handling multiple requests and responses for credential presentation.
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.
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.
The permission mediated by the user agent is not consent, which has specific legal definitions which can vary among different legal and regulatory environments and may need to be collected by the digital wallet before sharing information with the verifier, or by the verifier itself before initiating the request. With frameworks and regulations for obtaining consent still being developed, this API aims to enable the exchange of the necessary information, which could include the following:
As more of this information becomes available in a structured format, we expect user agents and this specification to leverage it to improve the user permission experience as well.
This section is a work in progress as this document evolves.