Skip to main content

Usage

warning

The EUDI Wallet provider (eudiw) is experimental. For now you can only use it on Testbed, and the API may still change in ways that need changes to your integration.

Create a transaction with provider set to eudiw and method set to auth. You specify which data to request using a DCQL query, and which ecosystem the transaction runs against. To try it out, see Testing.

Create a transaction​

This request creates a transaction on Testbed with the germany ecosystem and a DCQL query for the name and date of birth in the German PID (person identification data). Add new transaction lists every parameter.

curl -X POST https://testbed-eid.scrive.com/api/v1/transaction/new \
-H "Authorization: Bearer <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"provider": "eudiw",
"method": "auth",
"providerParameters": {
"auth": {
"eudiw": {
"ecosystem": "germany",
"dcqlQuery": {
"credentials": [
{
"id": "pid",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:eudi:pid:de:1"] },
"claims": [
{ "path": ["given_name"] },
{ "path": ["family_name"] },
{ "path": ["birthdate"] }
]
}
]
}
}
}
},
"redirectUrl": "https://your-app.example.com/eid/return"
}'

Ecosystem​

The ecosystem parameter decides which relying party credentials eID Hub uses and which credential issuers it trusts. Each wallet belongs to an ecosystem, and an ecosystem only works in the eID Hub environments that are configured for it. A transaction with an ecosystem that is not configured in the environment is rejected. These ecosystems are available on Testbed:

EcosystemWallet
germanyd-you, Germany's EUDI Wallet, in its sandbox
internalThe EU reference wallet. internal is Scrive's own test ecosystem.

DCQL query​

The dcqlQuery parameter tells the wallet what to share. DCQL (Digital Credentials Query Language) is defined in section 6 of OpenID for Verifiable Presentations 1.0. eID Hub validates the query and sends it to the wallet as is, so the credential type and claim names must match what the wallet holds.

A DCQL query lists the credentials you ask for under credentials. For each one you set an id of your choice, the format, the credential type in meta, and the claims you want, each with the path to that piece of data. The wallet only discloses the claims you ask for.

These samples request the German PID in the SD-JWT VC format. Use them with the germany ecosystem. On Testbed, eID Hub only accepts the German PID as SD-JWT VC, not as mdoc (mso_mdoc).

Name, date of birth, address and nationality, from the German PID presentation example:

{
"credentials": [
{
"id": "pid",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:eudi:pid:de:1"] },
"claims": [
{ "path": ["given_name"] },
{ "path": ["family_name"] },
{ "path": ["birthdate"] },
{ "path": ["address", "street_address"] },
{ "path": ["address", "postal_code"] },
{ "path": ["address", "locality"] },
{ "path": ["address", "country"] },
{ "path": ["nationalities"] }
]
}
]
}

Only whether the person is 18 or older, without the date of birth or any other claim:

{
"credentials": [
{
"id": "pid",
"format": "dc+sd-jwt",
"meta": { "vct_values": ["urn:eudi:pid:de:1"] },
"claims": [{ "path": ["age_equal_or_over", "18"] }]
}
]
}

The available claims depend on the credential. The German PID reference lists every claim of the German PID and its name.

Flow​

In the same-device flow, the user is on the phone that has the wallet app. Send them to accessUrl. eID Hub's page opens the wallet, the wallet returns the user to that page's browser, and eID Hub redirects it to your redirectUrl. The transaction only completes when the user comes back in the browser that opened eID Hub's page, so don't open sameDeviceUrl directly.

In the cross-device flow, the user scans a QR code with the phone that has the wallet app. Either send them to accessUrl on their computer, where eID Hub's page shows the QR code, or start the transaction through the API and show crossDeviceUrl from the response as a QR code in your own UI. Then poll the transaction until it is complete. See Result handling.

Which flows work depends on the wallet. The EU reference wallet supports both, and d-you supports the same-device flow only. See each wallet's section in Testing.

Completion data​

When the transaction status is complete, fetch it with Get a transaction. The shared data is in providerInfo.eudiwAuth.walletResponse, keyed by the id of each credential query. Each value is a list of presentations. A presentation holds the claims you asked for, plus claims the wallet always shares, such as vct, exp and cnf.

This is the response to the name, date of birth, address and nationality sample above, with example values. It is shortened: only status and the wallet data are shown, and the technical claims other than vct are left out.

{
"status": "complete",
"providerInfo": {
"eudiwAuth": {
"walletResponseStatus": "read",
"walletResponse": {
"pid": [
{
"vct": "urn:eudi:pid:de:1",
"given_name": "ERIKA",
"family_name": "MUSTERMANN",
"birthdate": "1983-08-12",
"address": {
"street_address": "HEIDESTRASSE 17",
"postal_code": "51147",
"locality": "KÖLN",
"country": "DE"
},
"nationalities": ["DE"]
}
]
}
}
}
}

Data retention​

eID Hub keeps wallet data for a much shorter time than data from other providers. eID Hub deletes it about a minute after you first read it, or after about ten minutes if nobody reads it. walletResponseStatus shows where the data is: pending until the wallet responds, available once the data can be read, read after the first read, and expired if nobody read it in time and it was deleted. Read the data as soon as the transaction completes and store what you need. See Data retention.

warning

Scrive cannot recover wallet data after it has been deleted.

Errors​

While the transaction is started, errorData holds the last error the wallet reported, for example when the user declines, or an error eID Hub raised while verifying the wallet's response. Its error field holds an OpenID4VP error code or a verification error, and errorDescription can add details. An error does not end the transaction, so the user can try again.

A transaction that is not complete within about ten minutes of its start fails with the error expired. This is not the same as the expired value of walletResponseStatus. You can also cancel a started transaction with Cancel a transaction.