Copyright © 2025 the Contributors to the Digital Credentials Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.
This document specifies an API to enable user agents to mediate access to, and presentation 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 a digital credential from a user agent or underlying platform.
This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.
This is an unofficial proposal.
GitHub Issues are preferred for discussion of this specification.
This document defines an API enabling a website to request presentation of a digital credential.
The API design is agnostic to both credential presentation exchange protocols and credential formats. However, to promote interoperability this document includes a 9. Registry of protocols.
The API is designed to support the following goals:
Digital credentials of many types can be presented 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:
WebIDLpartial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
The digital member
allows for options to configure the request for a digital credential.
WebIDLdictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialRequest> requests;
};
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.
The DigitalCredentialRequest dictionary represents a presentation request. It is used to specify an exchange protocol and a request data,
which the user agent MAY match against software used by a holder, such as
a digital wallet.
WebIDLdictionary DigitalCredentialRequest {
required DOMString protocol;
required object data;
};
The protocol member
denotes the exchange protocol when requesting an
identify credential.
The protocol member's value is be one of the
well-defined keys defined in 9.
Registry of protocols or any other custom
one.
The data member is the
request data to be handled by the holder's
software, such as a digital wallet.
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;
};
DigitalCredential instances are origin bound.
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.
Define appropriate:
[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors). [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) is appropriate for credentials that remain effective forever and can therefore simply be copied out of the credential store
[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors). [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) is appropriate for credentials that need to be re-generated from a credential source.
[[Store]](credential, sameOriginWithAncestors) methods on ExampleCredential's interface object.
Long-running operations, like those in PublicKeyCredential's [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operations are encouraged to use options.signal to allow developers to abort the operation. See DOM §3.3 Using AbortController and AbortSignal objects in APIs for detailed instructions.
ExampleCredential's [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) internal method is called with an origin (origin), a CredentialRequestOptions object (options), and a boolean which is true iff the calling context is same-origin with its ancestors. The algorithm returns a set of Credential objects that match the options provided. If no matching Credential objects are available, the returned set will be empty.
Define the value of the ExampleCredential interface object's [[type]] slot:
Define the value of the ExampleCredential interface object's [[discovery]] slot:
Extend (using partial dictionary) CredentialRequestOptions with the options the new credential type needs to respond reasonably to get().
Extend (using partial dictionary) CredentialCreationOptions with the data the new credential type needs to create Credential objects in response to create().
You might also find that new primitives are necessary. For instance, you might want to return many Credential objects rather than just one in some sort of complicated, multi-factor sign-in process. That might be accomplished in a generic fashion by adding a getAll() method to CredentialsContainer which returned a sequence<Credential>, and defining a reasonable mechanism for dealing with requesting credentials of distinct types.
The protocol member is the
exchange protocol that was used to request the
digital credential.
The data member is the
credential's response data. It contains the subset of JSON-parseable
object types.
When invoked, the [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method MUST:
Document.
NotAllowedError" DOMException.
NotAllowedError" DOMException.
digital's
requests member.
TypeError.
DigitalCredential.
When invoked, the [[Store]](credential, sameOriginWithAncestors)
MUST call the default implementation of Credential's
[[Store]](credential, sameOriginWithAncestors) internal
method with the same arguments.
When invoked, the [[Create]](origin, options,
sameOriginWithAncestors) internal method MUST call the default
implementation of Credential's [[Create]](origin, options, sameOriginWithAncestors) internal method with the same
arguments.
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".
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.
This specification defines a policy-controlled feature identified by the string "digital-credentials-get". Its default allowlist is 'self'.
The following is the registry of exchange 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 exchange protocol:
DigitalCredentialsProvider's request
is converted to before it is passed onto
underlying platform).
DigitalCredential's data is converted before it is made available to the relying party).
To be included as a presentation protocol in the registry (used with
navigator.credentials.get), the exchange protocol:
To add a new exchange protocol to the registry, or to update an existing one:
navigator.credentials.get or "Issuance" for issuance
protocols used with navigator.credentials.create.
We need to come up with a registry governance and inclusion criteria.
For inclusion, at a minimum, there should be implementation support, and we talked about having some privacy checks too.
User agents MUST support the following exchange protocols:
| Protocol identifier | Type | Specification |
|---|---|---|
| Coming soon... | ||
This section is non-normative.
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 non-normative.
This section is a work in progress as this document evolves.
The documents listed below outline various privacy considerations for Digital Credentials, both broadly and for presentation on the web. Their contents will be integrated into this document gradually.
Explain how the API could be used to unnecessarily request digital credentials from individuals such as requesting a driver's license to log into a movie rating website and how the ecosystem can mitigate this risk.
Explain how the API could be used to request more data than necessary for a transaction and how the ecosystem can mitigate that over collection.
Explain how the API acquires an individual's consent to share a digital credential and how digital wallets can also provide further consent when sharing information.
Explain how verifiers might retain data and what the ecosystem does to mitigate excessive data retention policies.
Explain to what extent the API complies with known privacy regulations (e.g., consent) and what parts of those regulations are not possible to enforce via the API (e.g., retention).
Explain how selective disclosure and unlinkable disclosure help preserve privacy as well as their limitations in doing so.
Explain how some systems might "phone home", the impact on privacy that might have, and what the ecosystem provides to mitigate the risk.
Explain that the API does enable the transmission of personally identifiable information and that it does its best to ensure there is informed consent by the individual, but that the consent might be provided due to exhaustion or not understanding what PII is being transmitted and how to mitigate those concerns.
This section is non-normative.
This section is a work in progress as this document evolves.
WebIDLpartial dictionary CredentialRequestOptions {
DigitalCredentialRequestOptions digital;
};
dictionary DigitalCredentialRequestOptions {
sequence<DigitalCredentialRequest> requests;
};
dictionary DigitalCredentialRequest {
required DOMString protocol;
required object data;
};
[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
readonly attribute DOMString protocol;
[SameObject] readonly attribute object data;
};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 and MUST 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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: