Digital Credentials

https://www.w3.org/TR/digital-credentials/
Admin
Digital Credentials is a web API specification that enables user agents to mediate the presentation...
Tokens:20,772
Snippets:151
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Request digital credential issuance with navigator.credentials.create()

Source: https://www.w3.org/TR/digital-credentials

Use this example to request issuance of a digital credential via the Digital Credentials API. It checks protocol support with DigitalCredential.userAgentAllowsProtocol() and falls back to a traditional form if unsupported. The navigator.credentials.create() call initiates the issuance flow and logs any errors.

```html
<button>Request Digital Credential Issuance</button>
<script>
  const button = document.querySelector("button");
  button.addEventListener("click", async () => {
    const protocol = "example-issuance-protocol";
    // Check for DC API and protocol support
    if (!DigitalCredential.userAgentAllowsProtocol(protocol)) {
      // The browser doesn't allow the use of this protocol.
      // Fall back to a different issuance method.
      showTraditionalIssuanceForm();
      return;
    }
    try {
      const credential = await navigator.credentials.create({
        digital: {
          requests: [{
            protocol,
            data: { /* issuance request data */ }
          }]
        }
      });
    } catch (error) {
      console.error("Error issuing digital credential:", error);
    }
  });
</script>
```

--------------------------------

### Simulating a wallet error with AbortController

Source: https://www.w3.org/TR/digital-credentials

Simulates a wallet error by aborting the credential request with an AbortController. The abort reason is a DOMException with name "OperationError", and the example asserts that the caught error has that name.

```javascript
(async () => {
  const controller = new AbortController();
  const credentialPromise = navigator.credentials.get({
    digital: {
      requests: [{
        protocol: "example-request-protocol",
        data: { /* presentation request data */ }
      }]
    },
    signal: controller.signal
  });

  controller.abort(
    new DOMException("Simulated wallet failure", "OperationError")
  );

  try {
    await credentialPromise;
  } catch (error) {
    console.assert(error.name === "OperationError");
  }
})();

```

--------------------------------

### Request a digital credential with navigator.credentials.get()

Source: https://www.w3.org/TR/digital-credentials

Requests a digital credential via navigator.credentials.get() with a digital request. Includes protocol check, fallback, and posting the credential to a verifier server.

```html
<button>Verify Identity</button>
<script>
  const button = document.querySelector("button");
  button.addEventListener("click", async () => {
    const protocol = "example-request-protocol";
    // Check for DC API and protocol support
    if (!DigitalCredential.userAgentAllowsProtocol(protocol)) {
      // The browser doesn't allow the use of this protocol.
      // Fall back to a different verification method.
      showTraditionalVerificationForm();
      return;
    }
    try {
      const credential = await navigator.credentials.get({
        digital: {
          requests: [{
            protocol,
            data: { /* presentation request data */ }
          }]
        }
      });

      // Post it back to the verifier server for decryption and verification
      const response = await fetch("/verify-credential", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify(credential)
      });

      // Check response
      if (!response.ok) {
        throw new Error("Failed to verify credential");
      }

      // Render the verification result
      displayVerificationResult(await response.json());

    } catch (error) {
      console.error("Error requesting digital credential:", error);
    }
  });
</script>
```

--------------------------------

### navigator.credentials.create()

Source: https://www.w3.org/TR/digital-credentials

Requests issuance of a digital credential, which presents a credential manager chooser to the user for selecting a credential manager to save the digital credential.

```APIDOC
## [POST] navigator.credentials.create()

### Description
Requests issuance of a digital credential, which presents a credential manager chooser to the user for selecting a credential manager to save the digital credential.

### Method
POST

### Endpoint
navigator.credentials.create()

### Parameters
#### Request Body
- **digital** (DigitalCredentialCreationOptions) - Required - Options to configure the issuance of a digital credential.
  - **requests** (sequence<DigitalCredentialCreateRequest>) - Required - Specifies an issuance protocol and issuance request data.
    - **protocol** (DOMString) - Required - The issuance protocol identifier.
    - **data** (object) - Required - The issuance request data to be handled by the holder's credential manager.

### Request Example
{
  "digital": {
    "requests": [
      {
        "protocol": "example-protocol",
        "data": {}
      }
    ]
  }
}

### Response
#### Success Response (200)
- **credential** (DigitalCredential) - The response data containing the protocol-specific response from the holder's credential manager.

#### Response Example
{
  "credential": {}
}
```

--------------------------------

### Check multiple protocols with userAgentAllowsProtocol()

Source: https://www.w3.org/TR/digital-credentials

Filters a list of protocols to find which ones are supported by the user agent. Use this to determine if any protocol is available before proceeding.

```javascript
const protocols = [
  "example-issuance-protocol",
  "another-issuance-protocol"
];
const supportedProtocols = protocols.filter(DigitalCredential.userAgentAllowsProtocol);
if (supportedProtocols.length > 0) {
  // At least one protocol is supported. Proceed with issuance.
} else {
  // No protocols are supported. Fall back to a different issuance method.
}
```

--------------------------------

### CDDL types for digitalCredentials module

Source: https://www.w3.org/TR/digital-credentials

Defines the VirtualWalletAction type and the parameters for the setVirtualWalletBehavior command. The action can be "decline", "respond", "wait", or "clear". The parameters include optional context, protocol, and response fields.

```CDDL
CDDL
digitalCredentials.VirtualWalletAction = "decline" / "respond" / "wait" / "clear"

digitalCredentials.SetVirtualWalletBehaviorParameters = {
  action: digitalCredentials.VirtualWalletAction,
  ? context: text,
  ? protocol: text,
  ? response: { * text => any },
}

```

--------------------------------

### navigator.credentials.get()

Source: https://www.w3.org/TR/digital-credentials

Requests a digital credential from the user agent, which presents a chooser to the user for selecting a digital credential that can fulfill the request.

```APIDOC
## [GET] navigator.credentials.get()

### Description
Requests a digital credential from the user agent, which presents a chooser to the user for selecting a digital credential that can fulfill the request.

### Method
GET

### Endpoint
navigator.credentials.get()

### Parameters
#### Request Body
- **digital** (DigitalCredentialRequestOptions) - Required - Options to configure the request for a digital credential.
  - **requests** (sequence<DigitalCredentialGetRequest>) - Required - Specifies a presentation protocol and presentation request data.
    - **protocol** (DOMString) - Required - The presentation protocol identifier.
    - **data** (object) - Required - The presentation request data to be handled by the holder's credential manager.

### Request Example
{
  "digital": {
    "requests": [
      {
        "protocol": "example-protocol",
        "data": {}
      }
    ]
  }
}

### Response
#### Success Response (200)
- **credential** (DigitalCredential) - The selected digital credential.

#### Response Example
{
  "credential": {}
}
```

--------------------------------

### DigitalCredentialPresentationProtocol Enumeration

Source: https://www.w3.org/TR/digital-credentials

Documentation for the DigitalCredentialPresentationProtocol enumeration, listing the supported presentation protocols.

```APIDOC
## [Enumeration] DigitalCredentialPresentationProtocol

### Description
This enumeration's values correspond to the supported presentation protocols listed in the specification's Protocols section.

### Values
- `"openid4vp-v1-unsigned"`
- `"openid4vp-v1-signed"`
- `"openid4vp-v1-multisigned"`
- `"org-iso-mdoc"`

### WebIDL
```webidl
enum DigitalCredentialPresentationProtocol {
  "openid4vp-v1-unsigned",
  "openid4vp-v1-signed",
  "openid4vp-v1-multisigned",
  "org-iso-mdoc"
};
```
```

--------------------------------

### Prefer newer protocol with fallback using userAgentAllowsProtocol()

Source: https://www.w3.org/TR/digital-credentials

Selects the first supported protocol from an ordered list, preferring newer protocols and falling back to older ones on legacy browsers. Unknown protocols return false rather than throwing.

```javascript
// Ordered by preference; on browsers that implement DigitalCredential,
// unknown protocols return false rather than throwing.
const protocol = [
  "example-new-protocol",
  "example-legacy-protocol",
].find(DigitalCredential.userAgentAllowsProtocol);

if (protocol) {
  // Use the best protocol this browser supports.
} else {
  // No supported protocol found. Fall back to another approach.
}
```

--------------------------------

### digitalCredentials.setVirtualWalletBehavior

Source: https://www.w3.org/TR/digital-credentials

The digitalCredentials.setVirtualWalletBehavior command allows test automation to control how the user agent simulates a virtual wallet during credential requests. It supports actions to decline, respond with a predefined response, wait (leaving the promise unsettled), or clear the active behavior.

```APIDOC
## digitalCredentials.setVirtualWalletBehavior

### Description
Sets the virtual wallet behavior for the WebDriver session, simulating user actions during credential manager operations. This command is part of the optional `digitalCredentials` module for WebDriver BiDi.

### Method
Command

### Command
`digitalCredentials.setVirtualWalletBehavior`

### Parameters
- **action** (digitalCredentials.VirtualWalletAction) - Required - The virtual wallet action to simulate: `"decline"`, `"respond"`, `"wait"`, or `"clear"`.
- **context** (text) - Optional - The browsing context ID for which to set the behavior. If omitted, sets the default behavior.
- **protocol** (text) - Optional - The digital credential protocol. Required when `action` is `"respond"`.
- **response** (object) - Optional - The credential response to return. Required when `action` is `"respond"`.

### Return Type
`EmptyResult` - Returns success with data `null`.

### Errors
- **invalid argument** - Returned if `action` is `"respond"` and `protocol` or `response` is `null`, if `protocol` is not a valid `DigitalCredentialProtocol` enumeration value, if serializing `response` fails, or if `action` is not `"respond"` and `response` or `protocol` is not `null`.
```

--------------------------------

### Check protocol support with userAgentAllowsProtocol()

Source: https://www.w3.org/TR/digital-credentials

Checks if the user agent allows a specific protocol. Returns false for unknown protocols without throwing, but throws ReferenceError if DigitalCredential is not defined, so the typeof guard is required.

```javascript
if (DigitalCredential.userAgentAllowsProtocol("example-protocol")) {
  // DC API supported. Proceed with issuance or presentation.
} else {
  // DC API not supported. Fall back to, for example,
  // a traditional HTML form-based approach.
  showHTMLForm();
}
```

--------------------------------

### DigitalCredentialIssuanceProtocol Enumeration

Source: https://www.w3.org/TR/digital-credentials

Documentation for the DigitalCredentialIssuanceProtocol enumeration, listing the supported issuance protocols.

```APIDOC
## [Enumeration] DigitalCredentialIssuanceProtocol

### Description
This enumeration's values correspond to the supported issuance protocols listed in the specification's Protocols section.

### Values
- `"openid4vci-v1"`

### WebIDL
```webidl
enum DigitalCredentialIssuanceProtocol {
  "openid4vci-v1",
};
```
```

--------------------------------

### CDDL command definition for setVirtualWalletBehavior

Source: https://www.w3.org/TR/digital-credentials

Defines the command structure for digitalCredentials.setVirtualWalletBehavior, specifying the method name and parameters.

```CDDL
CDDL
digitalCredentials.SetVirtualWalletBehavior = (
  method: "digitalCredentials.setVirtualWalletBehavior",
  params: digitalCredentials.SetVirtualWalletBehaviorParameters
)

```
Tokens:
Raw