---
id: trust-anchors
title: "Manage Your Organisation's Trust Anchors"
description: Add, check and maintain the trust anchors of your organisation in the iGrant.io Organisation Wallet Suite (ETSI LOTE, ETSI TL and CA (X.509)), including the eight lists of the NXD Trust List for demos, interoperability tests and other non-production use.
hide_title: false
sidebar_label: Manage Trust Anchors
keywords: [trust anchors, trust sources, ETSI LOTE, ETSI TL, CA (X.509), trusted list, list of trusted entities, list signer certificate, Used As, Accepted By, NXD Trust List, Organisation Wallet Suite]
slug: /trust-anchors/
---

> **Build this with an AI coding agent.** Install the iGrant.io Agent Skills, then ask your agent to build the integration:
>
> ```bash
> npx skills add L3-iGrant/skills
> ```

<head>
  <title>Manage Your Organisation's Trust Anchors | iGrant.io DevDocs</title>
  <meta name="description" content="Add, check and maintain the trust anchors of your organisation in the iGrant.io Organisation Wallet Suite (ETSI LOTE, ETSI TL and CA (X.509)), including the eight lists of the NXD Trust List for demos, interoperability tests and other non-production use."/>
</head>

import NoteBox from '@site/src/components/NoteBox';

<NoteBox title="Specifications:" variant="info">
<ul>
<li><a href="https://www.etsi.org/deliver/etsi_ts/119600_119699/119602/01.01.01_60/ts_119602v010101p.pdf" target="_blank" rel="noopener noreferrer">ETSI TS 119 602 V1.1.1</a> (kind ETSI LOTE) and <a href="https://www.etsi.org/deliver/etsi_ts/119600_119699/119612/02.04.01_60/ts_119612v020401p.pdf" target="_blank" rel="noopener noreferrer">ETSI TS 119 612 V2.4.1</a> (kind ETSI TL)</li>
<li><a href="https://www.rfc-editor.org/rfc/rfc5280" target="_blank" rel="noopener noreferrer">IETF RFC 5280</a> (kind CA (X.509): CA certificates and CRLs) and <a href="https://www.rfc-editor.org/rfc/rfc5914" target="_blank" rel="noopener noreferrer">IETF RFC 5914</a> (trust anchors)</li>
</ul>
</NoteBox>

## In short

* A **trust anchor** is something your organisation trusts directly: an ETSI list, or CA certificates that you add. Every trust check of the iGrant.io Organisation Wallet Suite uses only the trust anchors that you choose.
* Each trust anchor has one **kind** and one role, **Used As**. The kinds are **ETSI LOTE** (a List of Trusted Entities, ETSI TS 119 602), **ETSI TL** (a Trusted List, ETSI TS 119 612) and **CA (X.509)** (CA certificates in PEM).
* You manage them on the **Trust Anchors** page of the dashboard (**Issuer & Verifier > Trust Anchors**) or with the [Trust Sources API](/docs/category/openid4vc-api/trust-sources). The API calls a trust anchor a *trust source*.
* For demos, interoperability tests and other non-production use, add the lists of the **NXD Trust List**. For production, add the official EU lists.

## The Trust Anchors page

* **Counters:** Total, Current, Out of date, Expired and Not downloaded. Select a card to show only its trust anchors.
* **Search and filters:** search by name, and filter by **Kind** and **Used as**.
* **Table:** Name, Kind, Used As, State, Entries, Accepted By, Last Updated and Active.
  * **State:** select the **i** icon next to it to see what each state means.
  * **Entries:** for a list, how many [entries](/docs/trust-etsi-lists/#in-the-igrantio-organisation-wallet-suite) of the list the trust anchor uses for its role, of all the entries of the list, for example **49 of 54**. When it uses all the entries, the cell shows one number. For a CA (X.509) trust anchor, the number of its CA certificates.
    * Put the pointer on the number to read the roles of the other entries.
    * An amber **0 of 61** tells that no entry of the list has the role of the trust anchor, so the checks find no signer in it. Edit the trust anchor and choose a role of the list, or add the list again as a second trust anchor for the other role.
  * **Accepted By:** how many settings name the trust anchor in an accepted list. Select the number to see them.
* **Row menu:** **View the entries**, **Edit**, **Refresh the list** (a list only) and **Delete**.

Each change saves at once.

A sandbox uses the trust anchors of its main organisation. A change in a sandbox changes them for the main organisation and all its sandboxes.

## Add a trust anchor

In the dashboard, select the add icon next to **Trust Anchors**, then fill in the form:

1. **Kind.** Choose **ETSI LOTE (List of Trusted Entities)**, **ETSI TL (Trusted List)** or **CA (X.509)**. You cannot change the kind later.
2. **Name** (optional).
   * A list defaults to its scheme name, or else the last part of its URL.
   * A CA (X.509) defaults to the common name (CN) of its first certificate.
   * Give a list a name of your own when its URL ends in a generic file name such as `tl.xml`.
3. For a list:
   * **List URL**.
   * **List signer certificate** (optional). Take it from a source that you trust, for example the pointer to the list in a List of Trusted Lists.
4. For a **CA (X.509)**: the **CA certificates** in PEM, and optionally the CRLs of these CAs (`-----BEGIN X509 CRL-----`). Never paste a private key.
5. **Used as.** Choose the one role that the checks use this trust anchor for. See [Trust Roles](/docs/trust-roles/#the-role-of-an-entry).

**The form reads the list before you add it.** When the **List URL** field or the **List signer certificate** field loses the focus, the wallet reads the list, and saves nothing:
* Above **Used as**, the form shows **Roles of the list**: each role that the list gives its entries, with the number of entries, for example **PID provider (17)**. When the list names no role for some entries, **No role** gives their number. The edit form shows the roles of the stored copy of the list, until you change its URL or its signer certificate.
* If you did not choose a role yet, the form selects the role that has the most entries.
* Under **Used as**, a line tells how many entries of the list the trust anchor uses for the role that you chose. The line is amber when no entry has that role. You can still add the trust anchor, because the list can change, but the checks find no signer in it while no entry has the role. The role **Status issuer** is different: the wallet refuses a list that has no service with that role.
* If the wallet cannot read the list as a list of the kind you chose, or its signature does not verify with the list signer certificate you gave, the form shows the reason at the **List URL** field.

Select **Add**. The wallet reads the list again, and the notification tells you the result. If the wallet cannot use the list, nothing is saved, and the form shows the reason at the **List URL** field.

With the API, call [Add trust source](/docs/openid4vc-api/config-create-digital-wallet-open-id-trust-source/). To read a list before you add it, call [Preview trust source](/docs/openid4vc-api/config-preview-digital-wallet-open-id-trust-source/). An example of an add:

```bash
curl -X POST "https://demo-api.igrant.io/v4/config/ows/trust/sources" \
  -H "Authorization: ApiKey $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "etsi_lote",
    "name": "NXD Trust List: wallet providers",
    "url": "https://trustlist.nxd.foundation/trust-lists/NXD-TL-WalletProviders.xml",
    "usedFor": "wallet_provider"
  }'
```

The API values of the kinds are `etsi_lote`, `etsi_trusted_list` and `trust_anchor` (CA (X.509)). A CA (X.509) takes `certificates` (PEM text) in place of `url`. A list takes the optional `signerCertificates` (PEM text).

## Trust the NXD Trust List

The NXD Foundation (NordXDataspace Foundation) publishes the NXD Trust List: one list for each role. iGrant.io uses it by default for demos, interoperability tests and all other non-production use. Add the lists that your checks need:

| List URL (`https://trustlist.nxd.foundation/trust-lists/` plus) | Kind | Used As |
| --- | --- | --- |
| `NXD-TL-WalletProviders.xml` | ETSI LOTE | Wallet provider |
| `NXD-TL-PID.xml` | ETSI LOTE | PID provider |
| `NXD-TL-PubEAA.xml` | ETSI LOTE | PuB-EAA provider |
| `NXD-TL-QEAA.xml` | ETSI TL | QEAA provider |
| `NXD-TL-EAA.xml` | ETSI TL | EAA provider |
| `NXD-TL-WRPAC.xml` | ETSI LOTE | Access certificate provider |
| `NXD-TL-WRPRC.xml` | ETSI LOTE | Registration certificate provider (no check uses it yet) |

* **Two lists cannot be added yet:**
  * `NXD-TL-WRPRC.xml` has no entries today, and a list without entries is refused.
  * `NXD-TL-Registrars.xml` has no entries either, and no **Used As** role fits it.
* **XML, not JSON:** the six lists of trusted entities are also published as JSON, but add the XML form. The signature of the JSON form does not verify yet; see [Interoperability](/docs/trust-interoperability/#findings).
* **Signer certificate:** all NXD lists are signed with the same NXD Foundation certificate. The [WE BUILD List of Trusted Lists](https://webuild-consortium.github.io/wp4-trust-group/) gives it in its pointers to `NXD-TL-QEAA.xml` and `NXD-TL-EAA.xml`.

Then add each trust anchor to the accepted list of the settings that should use it:
* [Trust When Issuing](/docs/trust-issuance/)
* [Trust When Verifying](/docs/trust-verification/)
* [Trust in Your Wallet](/docs/trust-holder-wallet/)

## Keep a list current

| State | Meaning |
| --- | --- |
| **Current** | The wallet has a good copy, and the list is not past its next update. The checks use it. |
| **Out of date** | The list is past its next update, and no new copy has come yet. For 3 more days the checks use the last copy as usual. |
| **Expired** | The list is more than 3 days past its next update. The checks still use the last copy, but each match has a warning. |
| **Not downloaded** | The wallet has no good copy of the list. The checks do not use it until a download works. |
| **Off** | You turned the trust anchor off. The checks do not use it. |

A CA (X.509) trust anchor is **Current** while its CA certificates are valid, and **Expired** when one of them is past its end date.

* **Automatic refresh:** the wallet downloads a list again at its next update, or 24 hours after the last download if that is earlier.
* **Refresh the list:** in the row menu, or with [Refresh trust source](/docs/openid4vc-api/config-refresh-digital-wallet-open-id-trust-source/). You can refresh a list at most once every 5 minutes. An earlier refresh is refused with `429` and a `Retry-After` header.

## Look at the entries

**View the entries** (or a click on the row) opens the trust anchor:

* **List state:** kind, state, list URL, list type, sequence number, last download, last change of the list, next update, next refresh and signature.
* **Accepted by:** the settings that accept the trust anchor, also those of sandboxes, which carry the name of their sandbox. You can open a setting of the organisation that you are in.
* **Entries:** all the entries of the list, with the provider, the service, the status and the certificate of each entry.
  * Search the entries, and filter them by status, and with **All entries**, **Used** or **Not used**.
  * When the trust anchor does not use all the entries, a line tells how many entries it uses and the roles of the other entries. The line is amber when it uses no entry. The **Role** column then shows the role that the list gives each entry. **No role** tells that the list names no role for the entry, so the entry has the role of the trust anchor. **Not used** marks an entry for another role: its tooltip names that role. See [Trust Roles](/docs/trust-roles/#the-role-of-an-entry).
  * **No certificate** marks an entry whose list gives no certificate for its service, for example because the list names the key with a DID.

Select an entry to see its role, its provider, its service and the history of its status, its digital identities, and its certificate, which you can copy or download as PEM.

The same data is in the API: [List trust source entries](/docs/openid4vc-api/config-list-digital-wallet-open-id-trust-entry/) (with `used=all` for the entries that the trust anchor does not use) and [Read trust source entry](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-source-entry/).

## Change, turn off or delete a trust anchor

* **Edit:** change the name, the list URL, the list signer certificate, the CA certificates or the role. A new URL downloads the list again.
* **Active:** turn a trust anchor off to stop the checks from using it without deleting it.
* **In use:** a trust anchor that a setting accepts, or that a presentation definition names in `etsi_tl`, cannot be turned off or deleted, and its URL and role cannot change. Remove it from the accepted lists first. In the dashboard, a select of its **Active** switch shows the settings with **Show Settings**. In the API, [Read trust source usage](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-source-usage/) returns them, and a refused change returns `trust_source.in_use`.
* **Delete:** asks you to type `DELETE`, then deletes the trust anchor.

## API reference

| Operation | API |
| --- | --- |
| Read a list before the add, and save nothing | [Preview trust source](/docs/openid4vc-api/config-preview-digital-wallet-open-id-trust-source/) |
| Add | [Add trust source](/docs/openid4vc-api/config-create-digital-wallet-open-id-trust-source/) |
| List and filter (by name, kind, role and state) | [List trust sources](/docs/openid4vc-api/config-list-digital-wallet-open-id-trust-source/) |
| Read | [Read trust source](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-source/) |
| Change, turn on or off | [Update trust source](/docs/openid4vc-api/config-update-digital-wallet-open-id-trust-source/) |
| Delete | [Delete trust source](/docs/openid4vc-api/config-delete-digital-wallet-open-id-trust-source/) |
| Download a list again | [Refresh trust source](/docs/openid4vc-api/config-refresh-digital-wallet-open-id-trust-source/) |
| Where it is used | [Read trust source usage](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-source-usage/) |
| Counters | [Read trust source statistics](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-statistics/) |
| Entries | [List trust source entries](/docs/openid4vc-api/config-list-digital-wallet-open-id-trust-entry/), [Read trust source entry](/docs/openid4vc-api/config-read-digital-wallet-open-id-trust-source-entry/) |

## Related pages

* [Trusted Lists and Lists of Trusted Entities](/docs/trust-etsi-lists/)
* [Trust Roles: Wallet Providers, Issuers and Relying Parties](/docs/trust-roles/)
* [Read a Trust Check Result](/docs/trust-check-results/)
* [Register Your Organisation on a Trust List](/docs/trust-relying-party-registration/)
