Digital Credentials

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:

• Keep the acts of requesting and issuing separate from the specific exchange protocol and issuance protocol respectively; thereby enabling the extensibility of such protocols and credential formats.
• Require presentation requests and issuance requests to be unencrypted, enabling user-agent inspection for risk analysis.
• Assume opaque (i.e., encrypted) presentation responses and issuance responses, enabling issuers, verifiers, and holders to control where potentially sensitive personally identifiable information is exposed.
• Require transient activation to perform presentation requests or 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 presentation request.
• Enable platform-provided wallet selection UX when multiple wallet applications support an issuance request.
• Enable platforms to provide secure cross-device presentation requests and 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

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 standardized protocol used for exchanging a digital credential between a holder and a verifier. A protocol is identified by a protocol identifier. See section also 13. Registry of protocols.

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 protocol identifier. See also section 13. Registry of protocols.

Issuance request

An issuance request is a request to issue a digital credential composed of some issuance request data and an issuance protocol.

issuance request data

A data structure that an issuer or a user agent, via an issuance protocol, to request the issuance of a digital credential by an issuer.

Issuance response

A format that holder uses, via an issuance protocol, to respond to an issuance request by an issuer.

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 presentation request by a verifier.

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

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

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

WebIDLdictionary DigitalCredentialRequestOptions {
  sequence<DigitalCredentialGetRequest> requests;
};

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

WebIDLpartial dictionary CredentialCreationOptions {
  DigitalCredentialCreationOptions digital;
};

WebIDLdictionary DigitalCredentialCreationOptions {
  sequence<DigitalCredentialCreateRequest> requests;
};

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 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;
  static boolean userAgentAllowsProtocol(DOMString protocol);
};

DigitalCredential instances are origin bound.

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.

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;
  static boolean userAgentAllowsProtocol(DOMString protocol);
};

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, MUST, MUST NOT, 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.