Copyright © 2025 World Wide Web Consortium . W3C ® liability , trademark and permissive document license rules apply.
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.
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 an Editor's Draft.
Publication as an Editor's 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 .
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 13. 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:
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<DigitalCredentialGetRequest> 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
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;
};
The
protocol
member
denotes
the
exchange
protocol
.
The
protocol
member's
value
can
be
one
of
the
well-defined
protocol
identifiers
defined
in
13.
Registry
of
protocols
or
a
custom
protocol
identifier.
The
data
member
is
the
request
data
to
be
handled
by
the
holder's
credential
provider,
such
as
a
digital
identity
wallet.
WebIDLpartial dictionary CredentialCreationOptions {
DigitalCredentialCreationOptions digital;
};
The
digital
member
allows
for
options
to
configure
the
issuance
of
a
digital
credential
.
WebIDLdictionary DigitalCredentialCreationOptions {
sequence<DigitalCredentialCreateRequest> requests;
};
The
requests
specify
an
issuance
protocol
and
request
data
,
which
the
user
agent
MAY
forward
to
a
holder
.
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;
};
The
protocol
member
denotes
the
issuance
protocol
.
The
protocol
member's
value
is
be
one
of
the
well-defined
keys
defined
in
13.
Registry
of
protocols
or
any
other
custom
one.
The
data
member
is
the
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
"
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
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
.
The
data
member
is
the
credential's
response
data.
It
contains
the
subset
of
JSON-parseable
object
types.
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
.
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,
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:
Document
.
NotAllowedError
"
DOMException
.
NotAllowedError
"
DOMException
.
digital
's
requests
member.
TypeError
.
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
.
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' .
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.
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
member.
DigitalCredential
's
data
member.
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
.
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.
User
agents
SHOULD
mediate
presentation
and
issuance
requests
in
Progress
This
section
is
a
work
in
progress
as
this
document
evolves.
way
that
offers
support
for
a
wide
range
of
user
input
methods,
including
input
hardware
like
keyboards,
pointing
devices,
touch
screens,
voice
recognition,
etc.
Additionally,
user
agents
SHOULD
support
accessible
output
methods
during
these
requests
to
ensure
that
prompts
for
user
consent
during
such
requests
can
be
meaningfully
communicated
to
the
widest
range
of
end-users.
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;
};
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
,
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: