Skip to main content

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"
}
FieldUse
uriSame-device flow: open it on the phone. After the presentation the wallet sends the user to the redirectUri, if one is set.
crossDeviceUriQR 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.
sessionSession 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.

StatusCause
400The 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.
403The API client is not allowed to use this requestId.
404No 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 of PUBLIC_URL; an imported certificate without DNS name fails with 400.
  • 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 its kid from the federation metadata, and the wallet takes the verifier metadata from the trust chain. Needs openid_credential_verifier in federation.entityTypes and a valid federation.entityId (rule) in the issuance configuration, else 400.

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.

  1. 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_origin is required. Take it from your own configuration, never from end-user input: if your backend passes on the Origin header of the browser request it received, any website can have your verifier sign requests for it. The value is an http or https origin or URL; a path in it is ignored (https://shop.example.com/checkout stands for https://shop.example.com), and a value without scheme fails with 400. If the presentation configuration has allowedOrigins, the value must be one of them, and with exactly one listed origin you can leave it out. The Origin and Host headers of this call are not used; before 10.0, EUDIPLO fell back to them.

  2. Your backend reads the signed request object from GET /api/session/{session} (field requestObject) and hands it to the page.

  3. The page calls the wallet:

    const credential = await navigator.credentials.get({
    mediation: "required",
    digital: {
    requests: [
    { protocol: "openid4vp-v1-signed", data: { request: requestObject } },
    ],
    },
    });
  4. The page posts the wallet response unchanged to the response_uri claim 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 200 with {} or { "redirect_uri": "..." }. A presentation that fails verification is answered with 400; 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": true and 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_mdoc credential of the DCQL query is requested; its meta.doctype_value is required. Other credentials, credential_sets and claim_sets are ignored.
  • Every element is requested with intent to retain false, whatever intent_to_retain says.
  • 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.
  • redirectUri and clientIdScheme from the request are ignored; the configuration's redirectUri still applies after a successful presentation.
  • The request cannot carry transaction data, so it answers 400 when the request sets transaction_data entries, 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_origin must equal the origin of the page that calls the DC API, because the session transcript is bound to it. The same rules as for dc-api apply: it is required unless the configuration's allowedOrigins lists exactly one origin, and must be one of them when they are set.
  • Elements the wallet does not return are not rejected separately, and values constraints are not checked; check the claims in the result.
  • Set readerAuth to sign the request so the wallet can authenticate the verifier.