Digital Credentials

TBW

There are many types of digital credential that can be conveyed using this API. Examples of these types include:

• a driver's license or identity card issued by a government institution
• TBW: other credential types

Digital credential

A cryptographically signed digital document containing one or more claims made by an issuer about one or more subjects.

Note: Focus on digital credentials about people

This specification is currently focused on digital credentials pertaining to people.

Exchange protocol

A protocol used for exchanging a digital credential between a holder and a verifier. See section 9. Registry of protocols for requesting digital credential.

Presentation request

A presentation request is a request for a digital credential composed of request data and a exchange protocol.

Presentation response

A format that a holder's software, such as a digital wallet, uses, via an exchange protocol, to respond to a request data by a verifier.

request data

A format that verifier software or a user agent uses, via an exchange protocol, to request a digital credential from a holder.

The following items are within the scope of this specification:

• Requesting a digital credential, including mechanisms for secure presentation.
• 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:

• Issuance process for establishing a digital credential.
• UI/UX considerations, with the exception of privacy considerations, which are addressed to ensure the protection of user data during the request process.

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

WebIDLdictionary DigitalCredentialRequestOptions {
  sequence<DigitalCredentialsRequest> requests;
};

The DigitalCredentialsRequest 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 DigitalCredentialsRequest {
  required DOMString protocol;
  required object data;
};

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 {
  [Default] object toJSON();
  readonly attribute DOMString protocol;
  readonly attribute object data;
};

DigitalCredential instances are origin bound.

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.

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

dictionary DigitalCredentialRequestOptions {
  sequence<DigitalCredentialsRequest> requests;
};

dictionary DigitalCredentialsRequest {
  required DOMString protocol;
  required object data;
};

[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
  [Default] object toJSON();
  readonly attribute DOMString protocol;
  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.