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 [=credential type examples|other types of digital credential=]. The API builds on [[[credential-management-1]]] as a means by which to request a digital credential from a user agent or underlying platform.
This is an unofficial proposal.
TBW
There are many types of digital credential that can be conveyed 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<DigitalCredentialsProvider> providers;
};
The providers specify an [=digital credential/exchange protocol=] and [=digital credential/query=], which the user agent MAY match against a holder's software, such as a digital wallet.
The {{DigitalCredentialsProvider}} dictionary is used to specify an [=digital credential/exchange protocol=] and a [=digital credential/query=], which the user agent MAY match against software used by a holder, such as a digital wallet.
dictionary DigitalCredentialsProvider {
required DOMString protocol;
required object request;
};
The protocol member denotes the [=digital credential/exchange protocol=] when requesting an identify credential.
The {{DigitalCredentialsProvider/protocol}} member's value is be one of the well-defined keys defined in [[[#protocol-registry]]] or any other custom one.
The request member is the request 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 {{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;
readonly attribute object data;
};
{{DigitalCredential}} instances are [=Credential/origin bound=].
The protocol member is the [=digital credential/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:
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 MUST call the default implementation of {{Credential}}'s {{Credential/[[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".
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'=].
The following is the registry of [=digital credential/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...
[=User agents=] MUST support the following [=digital credential/exchange protocols=]:
| Protocol identifier | Description | 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.
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.
This section is a work in progress as this document evolves.