Create Presentation Requests
Every verification starts with POST /api/verifier/offer. It creates a session from a presentation configuration and returns what you hand to the wallet or the browser. The caller needs the presentation:request or presentation:manage role; presentation:request, or sessions:read, can also read the resulting session (what sessions:read sees). An API client with allowedPresentationConfigs may only use the listed configurations.
Request body
The annotated body below is generated from the request schema at build time. Placeholder values and comments are for reference; it is not a ready-to-send payload. The nested webhook authentication shows one variant inline and the other as a comment.
{
// required; string; allowed: uri | dc-api | iso-18013-7; Response mode for the presentation request.
"response_type": "uri",
// required; string; Identifier of the presentation configuration to use.
"requestId": "string",
// optional; object; Inline webhook override; otherwise the configured webhook is used.
"webhook": {
// required; string; The URL to which the webhook will send notifications.
"url": "string",
// required; union; Webhook authentication strategy.
"auth": {
// required; string; allowed: apiKey; Use API key authentication.
"type": "apiKey",
// required; object; API key authentication settings.
"config": {
// required; string; The header name used to send the API key.
"headerName": "string",
// required; string; The API key value.
"value": "string"
}
},
// Alternative for auth: {"type":"none"}
// optional; array; List of credential IDs to include raw tokens for (for example ['sca_credential']).
"includeRawTokensFor": [
"string"
]
},
// optional; string; Redirect URI after completion; supports the {sessionId} placeholder.
"redirectUri": "string",
// optional; string; Origin of the page that calls the Digital Credentials API (dc-api, iso-18013-7), for example https://shop.example. Required for these response types unless allowedOrigins of the presentation configuration lists exactly one origin; must be one of allowedOrigins when they are set. Set it from your own configuration, never from end-user input such as a forwarded Origin header.
"expected_origin": "string",
// optional; array; Transaction data overriding the presentation configuration.
"transaction_data": [
{
// required; string; Transaction data type identifier.
"type": "string",
// required; array; Credential query ids this transaction data applies to.
"credential_ids": [
"string"
],
// optional; unknown; Transaction details. Required for TS12 SCA transaction data.
"payload": {}
}
],
// optional; number; minimum: 0; Clock skew override in seconds for credential JWT time validation.
"skewSeconds": 0,
// optional; string; allowed: x509_hash | x509_san_dns | openid_federation; OID4VP client identifier prefix; defaults to x509_hash. openid_federation uses the tenant's OpenID Federation entity id and needs openid_credential_verifier in federation.entityTypes of the issuance configuration.
"clientIdScheme": "x509_hash",
// optional; string; Your own reference for this request, e.g. an order or case id. Stored in plaintext, searchable in the session list, included in webhooks and kept when the session is anonymized. Must not contain personal data.
"reference": "string"
}
A minimal request only names the flow and the configuration:
{
"response_type": "uri",
"requestId": "membership-check"
}
Override rules
webhook, redirectUri, transaction_data and skewSeconds in the request replace the values of the presentation configuration for this session only. Values are replaced, not merged: a request webhook replaces the configuration's webhook endpoint, and request transaction_data replaces the whole configured list. clientIdScheme, expected_origin and reference exist only on requests. ISO 18013-7 requests use only webhook, skewSeconds, expected_origin and reference, and refuse transaction data (see below).
reference (optional, up to 255 characters) stores an identifier of your system with the session, for example an order or case ID. It is returned with the session, sent in the presentation webhook, and you can find the session by it later. It is stored in plaintext and stays when sessions are anonymized, so it must never contain personal data.
Response
{
"uri": "openid4vp://?client_id=x509_hash%3A...&request_uri=https%3A%2F%2Feudiplo.example.com%2Fpresentations%2F<walletNonce>%2Foid4vp%2Frequest&request_uri_method=get",
"crossDeviceUri": "openid4vp://?client_id=x509_hash%3A...&request_uri=https%3A%2F%2Feudiplo.example.com%2Fpresentations%2F<walletNonce>%2Foid4vp%2Frequest%2Fno-redirect&request_uri_method=get",
"session": "3f0c1d9e-4c1b-4f63-9a59-2f4f0b6a2c11"
}
| Field | Use |
|---|---|
uri | Same-device flow: open it on the phone. After the presentation the wallet sends the user to the redirectUri, if one is set. |
crossDeviceUri | QR code for a wallet on another device. The wallet fetches the request from .../request/no-redirect, so it never redirects, even if redirectUri is set. |
session | Session ID for receiving the result. The wallet never sees it; its URLs carry a separate random walletNonce. |
The request expires after the configuration's lifeTime (default 300 seconds). Create a new request for every verification: each one can be answered only once.
| Status | Cause |
|---|---|
400 | The body does not match the schema, x509_san_dns was requested for a certificate without DNS name, or openid_federation for a tenant without federation verifier entity, or, for dc-api and iso-18013-7, expected_origin is missing (unless allowedOrigins lists exactly one origin), not an http(s) origin, or not in the configuration's allowedOrigins. Also when a transaction_data entry, from the request or else the configuration, breaks the rules in Which credentials an entry may reference, or an iso-18013-7 request would carry transaction data. |
403 | The API client is not allowed to use this requestId. |
404 | No presentation configuration with this requestId exists, or no usable access key chain: none exists, accessKeyChainId points to none, or its certificate is invalid. |
QR code and same-device redirect
Use response_type: "uri" for both. Show crossDeviceUri as QR code when the user is on a computer; open uri when your page runs on the phone that has the wallet. For a same-device redirect, set redirectUri, for example https://shop.example.com/verified?session={sessionId}. EUDIPLO replaces {sessionId} and appends a one-time response_code, which your backend must check before it trusts the result (Receive Results).
Client identifier
The wallet identifies EUDIPLO by the client_id in the request, set by clientIdScheme:
x509_hash(default):x509_hash:<base64url SHA-256 of the leaf certificate>. Works with any access certificate, including self-signed ones.x509_san_dns:x509_san_dns:<first DNS name in the leaf certificate's subjectAltName>. Use it when a wallet only accepts DNS-based client identifiers. Certificates that EUDIPLO generates contain the host name ofPUBLIC_URL; an imported certificate without DNS name fails with400.openid_federation:openid_federation:<entity ID>of the tenant's OpenID Federation entity. The request object carries no certificate (x5c); the wallet picks the access key by itskidfrom the federation metadata, and the wallet takes the verifier metadata from the trust chain. Needsopenid_credential_verifierinfederation.entityTypesand a validfederation.entityId(rule) in the issuance configuration, else400.
Digital Credentials API
With response_type: "dc-api" the browser asks the wallet through navigator.credentials.get(); no QR code or app switch is needed. The wallet encrypts its answer for EUDIPLO (response_mode: dc_api.jwt) and binds it to the page's origin.
-
Your backend creates the request and passes the origin of the page that will call the DC API:
{"response_type": "dc-api","requestId": "membership-check","expected_origin": "https://shop.example.com"}expected_originis required. Take it from your own configuration, never from end-user input: if your backend passes on theOriginheader of the browser request it received, any website can have your verifier sign requests for it. The value is anhttporhttpsorigin or URL; a path in it is ignored (https://shop.example.com/checkoutstands forhttps://shop.example.com), and a value without scheme fails with400. If the presentation configuration hasallowedOrigins, the value must be one of them, and with exactly one listed origin you can leave it out. TheOriginandHostheaders of this call are not used; before 10.0, EUDIPLO fell back to them. -
Your backend reads the signed request object from
GET /api/session/{session}(fieldrequestObject) and hands it to the page. -
The page calls the wallet:
const credential = await navigator.credentials.get({mediation: "required",digital: {requests: [{ protocol: "openid4vp-v1-signed", data: { request: requestObject } },],},}); -
The page posts the wallet response unchanged to the
response_uriclaim of the request object (<PUBLIC_URL>/presentations/<walletNonce>/oid4vp):const result = await fetch(responseUri, {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify(credential.data),});EUDIPLO verifies the presentation and answers
200with{}or{ "redirect_uri": "..." }. A presentation that fails verification is answered with400; see What the wallet or browser receives. Your backend receives the result by webhook, SSE or polling as in the other flows. If the body also contains"sendResponse": trueand no redirect is configured, the answer contains the verified credentials.
@eudiplo/sdk-core wraps these steps. isDcApiAvailable() checks for browser support, and verifyWithDcApi() creates the request, calls the wallet and posts the response:
import { EudiploClient, isDcApiAvailable } from "@eudiplo/sdk-core";
const client = new EudiploClient({ baseUrl, clientId, clientSecret });
if (isDcApiAvailable()) {
const { credentials } = await client.verifyWithDcApi({ configId: "membership-check" });
}
verifyWithDcApi() runs entirely in the browser and needs the API client's secret there. Use it for demos only; in production, keep steps 1 and 2 on your backend. Anyone who copies the secret can create requests for any origin, so set allowedOrigins on the configurations such a client may use.
ISO 18013-7 Annex C
response_type: "iso-18013-7" uses the org-iso-mdoc protocol of the DC API, for browsers that do not support the OpenID4VP profile, such as Safari on iOS and macOS. It only requests mDOCs:
{
"response_type": "iso-18013-7",
"requestId": "pid-mdoc",
"expected_origin": "https://shop.example.com"
}
The response carries CBOR structures instead of a request URI (uri and crossDeviceUri are empty):
{
"session": "<session id>",
"uri": "",
"crossDeviceUri": "",
"org_iso_mdoc": {
"device_request": "<base64url CBOR DeviceRequest>",
"encryption_info": "<base64url CBOR EncryptionInfo>",
"response_uri": "https://eudiplo.example.com/presentations/<walletNonce>/iso-18013-7"
}
}
The page passes device_request and encryption_info to navigator.credentials.get() with protocol org-iso-mdoc and posts the wallet's encrypted response as { "data": "<base64url>" } to the response_uri. It ends with a random walletNonce, not the session ID: the endpoint answers the session ID with 404, so someone who only knows the session ID from the management API or a webhook cannot answer in the holder's place. Since 10.0; in 9.x the page posted to /presentations/{session}/iso-18013-7. EUDIPLO answers 200 with {} or { "redirect_uri": "..." }; a failed verification returns 400 with error and message (failure codes).
Differences from the OpenID4VP flows:
- Only the first
mso_mdoccredential of the DCQL query is requested; itsmeta.doctype_valueis required. Other credentials,credential_setsandclaim_setsare ignored. - Every element is requested with intent to retain
false, whateverintent_to_retainsays. - Request at least one claim. Without
claims, EUDIPLO still sends the request with an empty element list, which ISO 18013-5 does not allow, so wallets may reject it. redirectUriandclientIdSchemefrom the request are ignored; the configuration'sredirectUristill applies after a successful presentation.- The request cannot carry transaction data, so it answers
400when the request setstransaction_dataentries, or the configuration has some and the request does not send"transaction_data": []. Otherwise the session would complete without the holder authorizing the transaction. expected_originmust equal the origin of the page that calls the DC API, because the session transcript is bound to it. The same rules as fordc-apiapply: it is required unless the configuration'sallowedOriginslists exactly one origin, and must be one of them when they are set.- Elements the wallet does not return are not rejected separately, and
valuesconstraints are not checked; check the claims in the result. - Set
readerAuthto sign the request so the wallet can authenticate the verifier.