Verify Credentials with the Digital Credentials API
The Digital Credentials API (DC-API) is a browser API that lets a website request credentials from the wallets on a user's device. When your website calls it, the browser and operating system show the user the credentials that match the request, the user approves the presentation in their wallet, and the browser returns the wallet's response to your website.
Users can present in two ways:
- Same device: the user opens your website in their phone's browser, and the wallet on the same phone responds.
- Cross-device: the user opens your website in a desktop browser. The browser shows a QR code, and the user scans it with their phone to present from the wallet on their phone.
In both cases, the browser handles the connection to the wallet.
How it works
A DC-API verification involves your website frontend, your backend, and the Core:
- Your website frontend checks browser support, calls the Digital Credentials API, and passes the wallet's response to your backend.
- Your backend creates and shares the proof request with the Core, and submits the wallet's response to the Core. Your backend holds the API credentials; the browser never calls the Core directly.
- The Core builds the protocol-specific request, decrypts and verifies the wallet's response, and updates the proof request with the result.
This flow differs from the basic verification flow, where the wallet fetches the request from the Core and submits its response to the Core directly. With the DC-API, the request and the response pass through the browser and your website instead. Wallets never contact the Core, so the Core does not need to expose any public endpoints for this flow.
What you can request
The Core supports two verification protocols for the DC-API. Each one supports different credential formats:
| Verification protocol | Credential formats |
|---|---|
ISO_MDL | ISO mdoc |
OPENID4VP_FINAL1_HAIP | SD-JWT VC, ISO mdoc |
Which protocols a user can use depends on their browser, operating system, and wallet, and support is changing quickly. Rather than targeting specific platforms, your website detects which protocols the user's browser supports and creates a matching proof request. See Step 1.
For details on browser and platform support, see:
- Chrome: Digital Credentials API
- Apple: Requesting a mobile document on the web
Prerequisites
- Configuration: your configuration includes the
DC_APItransport. To use theISO_MDLprotocol, theISO_MDLverification protocol also needs thedcApiVerifierparameters. Both are in the base configuration; check that they are in yours. See the verification protocol configuration reference. - Verifier identifier: DC-API proof requests require a verifier identifier. Use the identifier your use case requires; for EUDI use cases, this is your Access Certificate. See Certificates.
- API permissions: submitting a wallet's response requires the
ProofSubmitResponsepermission. Grant it to the API client used by your website's backend. See Configure Access Control.
Verify a credential
1. Detect supported protocols
In your website frontend, check whether the browser supports the DC-API and which protocols it allows. Use the result to decide which verification protocol your backend uses for the proof request.
function selectVerificationProtocol() {
if (typeof DigitalCredential === 'undefined') {
return null; // DC-API not supported; offer another verification method
}
if (DigitalCredential.userAgentAllowsProtocol('openid4vp-v1-signed')) {
return 'OPENID4VP_FINAL1_HAIP';
}
if (DigitalCredential.userAgentAllowsProtocol('org-iso-mdoc')) {
return 'ISO_MDL';
}
return null;
}
The Core always signs OpenID4VP requests, so check for
openid4vp-v1-signed. When the browser supports both protocols, which
one to prefer is up to you.
2. Create the proof request
From your backend, create a proof request with:
transport:DC_APIprotocol: the verification protocol selected in step 1. The value references the configured instance of the verification protocol.proofSchemaId: a proof schema that requests credentials in a format the selected protocol supports. See What you can request and Proof Schemas.verifier: your verifier identifier
{
"proofSchemaId": "<proof schema ID>",
"verifier": "<verifier identifier ID>",
"protocol": "ISO_MDL",
"transport": ["DC_API"]
}
3. Share the proof request
Share the proof request, passing the origin of the website that will make the browser call.
{
"params": {
"dcApiOrigin": "https://www.example.com"
}
}
dcApiOrigin is the scheme and host of your website, with a port only if
it is not the default port. Do not include a path. The origin must match
the page that calls the browser API exactly; if it does not, the wallet
rejects the request.
For OpenID4VP requests, the client ID scheme must be one listed in the
verification protocol's verifier.supportedClientIdSchemes. The
OPENID4VP_FINAL1_HAIP instance in the base configuration supports only
x509_hash, so your verifier identifier must be a certificate. If your
instance supports several schemes, you can pass clientIdScheme to choose
one: x509_hash, x509_san_dns, or decentralized_identifier. With
x509_san_dns, the domain of your website must match the DNS name in your
certificate, or be a subdomain of it.
The response contains requestJson instead of a share URL:
{
"requestJson": "{\"protocol\":\"org-iso-mdoc\",\"data\":{\"deviceRequest\":\"...\",\"encryptionInfo\":\"...\"}}",
"expiresAt": "2026-11-18T10:00:00.000Z"
}
requestJson is a serialized request entry with two fields:
protocol:org-iso-mdocforISO_MDL, oropenid4vp-v1-signedforOPENID4VP_FINAL1_HAIPdata: the protocol-specific request
The request is valid until expiresAt. To get a new request, for example
after the previous one expired, call share again.
4. Request the credential in the browser
Pass requestJson to your website frontend. In response to a user
action, such as a button click, call the Digital Credentials API with the
request entry:
const { protocol, data } = JSON.parse(requestJson);
try {
const credential = await navigator.credentials.get({
mediation: 'required',
digital: {
requests: [{ protocol, data }],
},
});
const response = JSON.stringify({
protocol: credential.protocol,
data: credential.data,
});
// Send `response` and the proof request ID to your backend.
} catch (error) {
// The user canceled, or no wallet responded.
}
Serialize both protocol and data from the browser's response. Some
platform examples send only data to the backend, but the Core needs
both fields.
If the user cancels or no wallet responds, no further action is needed. The proof request expires on its own.
5. Submit the response
From your backend, submit the response to the Core:
POST /api/proof-request/v1/{proofId}/dc-api-response
{
"response": "{\"protocol\":\"org-iso-mdoc\",\"data\":{\"response\":\"...\"}}"
}
The Core decrypts and verifies the response before returning. The request fails if:
- the proof request does not exist or is not in a state that accepts a response
- the response cannot be parsed
- trust is mandatory and the submission is not trusted
Otherwise, the Core completes the verification and moves the proof request
to ACCEPTED or ERROR.
6. Get the result
Get the outcome as for any other proof request: retrieve the proof request details, or receive a state change notification through a webhook.
Troubleshooting
| Symptom | Likely cause |
|---|---|
DigitalCredential is undefined | The browser does not support the DC-API. Offer another verification method. |
| The wallet rejects the request | dcApiOrigin does not match the website's origin, or, with x509_san_dns, the website domain does not match the certificate. |
| Submitting the response fails | The proof request has expired or already completed, the response is not the full { protocol, data } object, or trust requirements are not met (see Enforcing an Ecosystem as a Verifier). |
The proof request is in ERROR | The response was received but did not pass verification. Check the proof request details. |