Digital Credentials

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 for requesting digital credential .

The API is designed to support the following goals:

• Keep the act of requesting separate from the specific protocol , thereby enabling the extensibility of the protocol and credential formats.
• Require requests to be unencrypted, enabling user-agent inspection for risk analysis.
• Assume responses opacity (encrypted responses), enabling verifiers and holders to control where potentially sensitive personally identifiable information is exposed.
• Require transient activation to perform requests , ensuring that sites cannot silently query for 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 requests .
• Enable platforms to potentially provide secure cross-device requests with proximity checks.

Digital credentials of many types can be presented 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

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<DigitalCredentialRequest> requests;
};

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 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 .

  partial interface DigitalCredential {
    static Promise isProtocolSupportedByClient(DOMString protocol);
  };

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<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.