Use when implementing the W3C Digital Credentials API for browser-based credential exchange. Covers: DigitalCredential interface, navigator.credentials.get() extensions, credential management integration, and permissions policy.
name: "w3c-dc-api-core"
description: "Use when implementing the W3C Digital Credentials API for browser-based credential exchange. Covers: DigitalCredential interface, navigator.credentials.get() extensions, credential management integration, and permissions policy."
sections:
- "Introduction"
- "Model"
- "Scope"
- "The Digital Credentials API"
- "Extensions to CredentialRequestOptions dictionary"
- "The DigitalCredentialRequestOptions dictionary"
- "The DigitalCredentialGetRequest dictionary"
- "Extensions to CredentialCreationOptions dictionary"
- "The DigitalCredentialCreationOptions dictionary"
- "The DigitalCredentialCreateRequest dictionary"
- "The DigitalCredential interface"
- "Integration with Credential Management API"
- "[[\DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal method"
- "[[\Store]](credential, sameOriginWithAncestors) internal method"
- "[[\Create]](origin, options, sameOriginWithAncestors) internal method"
- "[[\type]] internal slot"
- "[[\discovery]] internal slot"
- "User permission"
- "Permissions Policy integration"
- "Registry of protocols"
- "General inclusion criteria"
- "Change process"
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 [=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:
- Keep the acts of [=digital credential/presentation
requests|requesting=] and [=digital credential/issuance
requests|issuing=] separate from the specific [=digital
credential/exchange protocol=] and [=digital credential/issuance
protocol=] respectively; thereby enabling the extensibility of such
protocols and credential formats.
- Require [=digital credential/presentation requests=] and [=digital
credential/issuance requests=] to be unencrypted, enabling user-agent
inspection for risk analysis.
- Assume opaque (i.e., encrypted) [=digital credential/presentation
responses=] and [=digital credential/issuance responses=], enabling
issuers, verifiers, and holders to control where potentially sensitive
personally identifiable information is exposed.
- Require [=transient activation=] to perform [=digital
credential/presentation requests=] or [=digital credential/issuance
requests=], ensuring that sites cannot silently query for nor issue
digital credentials, nor communicate with wallet providers, without the
user's active participation and confirmation of each action.
- Enable platform-provided credential selection UX when multiple wallet
applications have credentials that match a [=digital
credential/presentation request=].
- Enable platform-provided wallet selection UX when multiple wallet
applications support an [=digital credential/issuance request=].
- Enable platforms to provide secure cross-device [=digital
credential/presentation requests=] and [=digital credential/issuance
requests=] with proximity checks.
[=Digital credentials=] of many types can be presented and issued using
this API. Examples of these
types include:
- a driving license, passport, or other identity card issued by a
government institution
- a travel authorization document issued by an embassy or consulate
- a proof of employment issued by a public or private organization
- a proof of education or professional training issued by an
institution
- and many other scenarios as described in Verifiable Credentials Use
Cases
Model
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=].
This specification is currently focused on digital credentials
pertaining to people.
Presentation request
A presentation request is a request for a [=digital credential=]
composed of [=digital credential/request data=] and a [=digital
credential/exchange protocol=].
request data
A format that [=verifier=] software or a [=user agent=] uses, via an
[=digital credential/exchange protocol=], to request a [=digital
credential=] from a [=holder=].
Presentation response
A format that a [=holder's=] software, such as a digital wallet, uses,
via an [=digital credential/exchange protocol=], to respond to a
[=digital credential/presentation request=] by a [=verifier=].
Issuance request
An issuance request is a request to issue a [=digital credential=]
composed of some [=digital credential/issuance request data=] and an
[=digital credential/issuance protocol=].
issuance request data
A data structure that an [=issuer=] or a [=user agent=], via an
[=digital credential/issuance protocol=], to request the issuance of a
[=digital credential=] by an [=issuer=].
Issuance response
A format that [=holder=] uses, via an [=digital credential/issuance
protocol=], to respond to an [=digital credential/issuance request=] by
an [=issuer=].
Exchange protocol
A standardized protocol used for exchanging a [=digital credential=]
between a [=holder=] and a [=verifier=]. A protocol is identified by a
[=digital credential/protocol identifier=]. See section also
[[[#protocol-registry]]].
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".
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 [=digital credential/protocol
identifier=]. See also section [[[#protocol-registry]]].
Scope
The following items are within the scope of this specification:
- Requesting a [=digital credential=], including mechanisms for secure
presentation.
- Requesting issuance of a [=digital credential=].
- Ensuring that when an API call is made, the website does not learn
anything about the a holder's [=digital credentials=] or their software
unless the [=user agent=] has previously received user consent.
- Ensuring that any installed application software will not learn
anything about a given [=request=] unless the [=holder=] explicitly
consents to use that software.
The following items are out of scope:
- UI/UX considerations, with the exception of privacy considerations,
which are addressed to ensure the protection of user data during the
request process.
The Digital Credentials API
The Digital Credentials API leverages the [[[credential-management]]]
specificaion, allowing [=user agents=] to mediate the [=digital
credential/issuance=] and [=digital credential/presentation=] of
[=digital credentials=].
The API allows [=digital credential/presentation request|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.`{{CredentialsContainer/get()}}
method, which runs the [=request a credential=] algorithm of
[[[credential-management]]]. That algorithm then calls back into this
specification's {{DigitalCredential}} interface's
{{DigitalCredential/[[DiscoverFromExternalSource]](origin, options,
sameOriginWithAncestors)}} internal method.
Additionally, the API also allows [=digital credential/Issuance
request|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.`{{CredentialsContainer/create()}} method, which
runs the [=create a credential=] algorithm of
[[[credential-management]]]. That algorithm then calls back into this
specification's {{DigitalCredential}} interface's
{{Credential/[[Create]](origin,options, sameOriginWithAncestors)}}
internal method.
Please see [[[#credential-management-integration]]] for complete details
of how to integrate with the [[[credential-management]]] specification.
The following example shows how to request a digital credential using
the Digital Credentials API. The entry point for the API is the
`navigator.credentials.`{{CredentialsContainer/get()}} method, which is
used to request a [=digital credential=] from the user agent. If the
user agent supports [=digital credential/presentation
requests|presentation=], it allows the user to select a digital
credential through a [=credential chooser=]:
```
By