Skip to main content

DCQL: Trusted Authorities

The trusted_authorities field in a DCQL query allows a verifier to restrict accepted credentials to those issued by specific trust anchors.

Scenario: A verifier requests a University Degree credential, and accepts it only when its issuer is on the EWC trusted list.

The API takes two types of trusted_authorities:

  • etsi_tl: the URL of an ETSI list. You select it from the ETSI list trust sources of your organisation (Step 2 adds one); any other value is rejected. The check uses the stored copy of that source, whose signer certificates guarantee its authenticity. It does not depend on the Require switch of the query, and it has no role. A holder of the Organisation Wallet must also accept the list (Step 3).
  • aki: the authority key identifier (base64url) of a CA in the certificate chain of the issuer. An aki value is only a filter to find the matching credentials, and it is no proof of trust.

For the underlying DCQL query, diagram and video walkthrough, see the “Basic credential query with trusted authority” use case in our DCQL concepts article.

Fig 01: Require a University Degree credential, only if issued by an authority listed in the trusted list.

Before you start: This example asks the holder wallet for credentials that it already holds. Issue them to your wallet first on Issue the Test Credentials:

Step 1: Get the API Key (Verifier Admin)​

To obtain your API key, sign in to the dashboard and go to Account > Developer APIs > Create API Key (see Get API Keys). Once you have your API key, enter it in the field below and click the Set API Key button to save it for future use.

Signing keys: The requests on this page that name a signing key sign with an x509 key of your organisation: a key with a certificate chain. After you set the API key, the page fills in such a key. To choose another key, click the key label next to a signing key field in a request, for example cryptographicKeyIdentifier. To create a key, attach a certificate or see your keys, follow the key management guide. To add your certificate to the NXD trust list, see trust list registration.

Step 2: Create Presentation Definition (Verifier Admin)​

To create a presentation definition for requesting proof, you can run the code block below using the Run button. Alternatively, you can manually copy the code block and use it in the body of the API request provided here.

Note: With cryptographicKeyFormat x509, the cryptographicKeyIdentifier must be a key of your organisation that has a certificate chain. The page fills in such a key after you set the API key. Use Select key on the request to choose another key, or see the key management guide.

  • First, add the EWC trusted list as a trust source of your organisation with Add Trust Source. Skip this call when your organisation already has a trust source with this URL: see List Trust Sources. Copy the id of the trust source (trustSource.id in the response) for Step 3.

    A trust source has one role, usedFor. Most services on the EWC trusted list have the service type EAA, and entries with a service type that the wallet does not map take the role of the trust source, so this example uses eaa_provider. For your own list, use the role of its entries. As the etsi_tl check has no role, this value does not affect the check of this query.

curl -X POST "https://demo-api.igrant.io/v4/config/ows/trust/sources" \
  -H "Authorization: ApiKey <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"kind": "etsi_trusted_list", "usedFor": "eaa_provider", "url": "https://raw.githubusercontent.com/EWC-consortium/ewc-trust-list/refs/heads/main/EWC-TL.xml"}'
  • Then create a presentation definition by running the code block below. The verifier rejects an etsi_tl value that is not the URL of an ETSI list trust source of your organisation.

Request

Response

Once a presentation definition has been created, the presentationDefinitionId is autofilled in Step 4 automatically (and updated whenever Step 2 is re-run). You can also reuse the same presentationDefinitionId to verify multiple credentials.

Step 3: Accept the ETSI List in the Holder Configuration (Holder Admin)​

A holder of the Organisation Wallet accepts an etsi_tl item in a request only when the list is in its acceptedEtsiTrustedLists. Otherwise, the holder rejects the request: the wallet sends access_denied with the reason to the verifier, and Receive Verification returns 400 (presentation.etsi_list_not_accepted). Complete these two tasks before the holder receives the verification request:

  1. Make sure that the holder's organisation has an ETSI list trust source with the URL of the etsi_tl value. When the verifier and the holder are the same organisation, this is the trust source from Step 2. For another organisation, make the Add Trust Source call from Step 2 with that organisation's API key, because acceptedEtsiTrustedLists holds the id of a trust source of the holder's organisation.
  2. Add the id of that trust source to acceptedEtsiTrustedLists with Update Holder Configuration.
curl -X PATCH "https://demo-api.igrant.io/v4/config/ows/holder/configuration" \
  -H "Authorization: ApiKey <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"acceptedEtsiTrustedLists": ["<trustSourceId>"]}'

The list that you send replaces the stored list, so include the IDs that are already in it (see Read Holder Configuration). This list has no switch and does not depend on requiresTrustedRelyingParty. The update rejects a trust source that is not an ETSI list (trust.accepted_list_not_an_etsi_list).

Step 4: Create Verification Request (Verifier/Relying Party)​

When you run Step 2 on this page, the presentationDefinitionId field below is autofilled automatically (and updated whenever Step 2 is re-run). If you are executing the APIs yourself, replace <presentationDefinitionId> with the ID obtained in Step 2. To create the verification request, execute the code block below using the Run button. Alternatively, you can manually copy the JSON and use it in the body of the API available here.

After receiving the response, toggle the button provided to dynamically generate a QR code. The EUDI Wallet/Holder can then accept the verification request using the Data Wallet (or any other EU Digital Identity Wallet) by either scanning the QR code or directly accessing the verification request on their mobile device, such as via a browser.

Request

Response

Step 5: Send and Receive Verifiable Presentation (Holder)​

The holder wallet consents to send the requested credentials.

  • Receive Verification:
    • Use the requestUrl (step 4) with the API available here to receive the verification.
    • Copy the presentationId from the JSON response received from Receive Verification for the filter call.
  • Filter Verification:
    • Use that presentationId with the API available here to find matching credentials.
    • Save the <id> and <credentialId> from the response.
  • Send Verification:
    • Use the presentationId, <id> and <credentialId> with the API available here to send the credentials to the verifier.

Step 6: Send and Receive Verifiable Presentation (Verifier/Relying Party)​

  • The verifier (relying party) receives the requested credentials. Read them with the Read Verification API. In the response, isVerified holds the result, presentation holds the disclosed claims of each credential, and presentationValidity holds the result of each check.
  • vpToken holds the raw tokens that the wallet sent. Decode an SD-JWT or a JWT token with the JWT Decoder.