---
title: "Trust Source Management"
description: "Manage the trust sources loaded into your Trust Registry Service. Each trust source is identified by a unique sourceId and contains entities, services, and certificate identities parsed from a trust list."
stack: "Enterprise Stack (commercial) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/services/trust-registry-service/trust-source-management
generated: 2026-07-20
---
# Trust Source Management

Manage the trust sources loaded into your Trust Registry Service. Each trust source is identified by a unique `sourceId` and contains entities, services, and certificate identities parsed from a trust list.

## Load a Trust Source

Load a trust list into the Trust Registry from a remote URL or inline content. Each source is identified by a unique `sourceId`.

### Load from URL

**Option: CURL**

**Endpoint:** `POST /v1/{target}/trust-registry-api/sources/load` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Trust%20Registry/post_v1__target__trust_registry_api_sources_load)

##### Example Request

```bash
curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/trust-registry-api/sources/load' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "sourceId": "ewc-pilot",
  "url": "https://ewc-consortium.github.io/ewc-trust-list/EWC-TL",
  "validateSignature": false
}'
```

**Path Parameters**

- `orgID`: _String_ - Your organization's Base URL prefix, e.g. `myorg.enterprise-sandbox.waltid.dev`.
- `target`: _String_ - The Trust Registry service path, e.g. `myorg.tenant1.trust-registry`.

**Header Parameters**

- `Authorization`: _String_ - Bearer token for your organization.

**Body**

- `sourceId`: _String_ - Unique identifier for this trust source.
- `url`: _String_ - URL to fetch the trust list from. Either `url` or `content` must be provided.
- `validateSignature`: _Boolean_ - Whether to validate the XMLDSig signature. Use `true` for official production trust lists, `false` for unsigned pilot lists.

---

##### Example Response

```json
{
  "sourceId": "ewc-pilot",
  "success": true,
  "entitiesLoaded": 19,
  "servicesLoaded": 29,
  "identitiesLoaded": 38
}
```

If the source could not be loaded (e.g. network failure or signature validation failure), the response is still `200` but with `success: false` and an `error` description:

```json
{
  "sourceId": "ewc-pilot",
  "success": false,
  "error": "Failed to fetch from https://ewc-consortium.github.io/ewc-trust-list/EWC-TL: Connection timed out"
}
```

| Status | Description |
|--------|-------------|
| `200` | Request processed — check `success` field in the response body |
| `422` | Source could not be loaded — returned when loading fails at the trust list parsing level |

### Load from Content

For local or custom trust lists, provide the content directly instead of a URL.

**Option: CURL**

**Endpoint:** `POST /v1/{target}/trust-registry-api/sources/load` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Trust%20Registry/post_v1__target__trust_registry_api_sources_load)

##### Example Request

```bash
curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/trust-registry-api/sources/load' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "sourceId": "my-custom-list",
  "content": "{\"listMetadata\":{\"listId\":\"my-list\",\"listType\":\"mdl-issuers\",\"territory\":\"US\"},\"trustedEntities\":[...]}",
  "validateSignature": false
}'
```

**Path Parameters**

- `orgID`: _String_ - Your organization's Base URL prefix.
- `target`: _String_ - The Trust Registry service path.

**Header Parameters**

- `Authorization`: _String_ - Bearer token for your organization.

**Body**

- `sourceId`: _String_ - Unique identifier for this trust source.
- `content`: _String_ - The trust list content as a JSON string (LoTE format) or XML string (TSL format). Either `content` or `url` must be provided.
- `validateSignature`: _Boolean_ - Whether to validate the XMLDSig signature.

---

##### Example Response

```json
{
  "sourceId": "my-custom-list",
  "success": true,
  "entitiesLoaded": 4,
  "servicesLoaded": 6,
  "identitiesLoaded": 8
}
```

If the content cannot be parsed or signature validation fails, the response is still `200` but with `success: false` and an `error` description:

```json
{
  "sourceId": "my-custom-list",
  "success": false,
  "error": "XMLDSig signature validation failed: Signature validation failed - digest mismatch"
}
```

| Status | Description |
|--------|-------------|
| `200` | Request processed — check `success` field in the response body |
| `422` | Source could not be loaded — returned when loading fails at the trust list parsing level |

**Info:**

XMLDSig signature validation provides cryptographic assurance that a trust list has not been tampered with. Always set `validateSignature: true` when loading official production trust lists. Use `validateSignature: false` only for unsigned pilot or test lists.

## List Loaded Sources

**Option: CURL**

**Endpoint:** `GET /v1/{target}/trust-registry-api/sources` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Trust%20Registry/get_v1__target__trust_registry_api_sources)

##### Example Request

```bash
curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/trust-registry-api/sources' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'
```

**Path Parameters**

- `orgID`: _String_ - Your organization's Base URL prefix.
- `target`: _String_ - The Trust Registry service path.

**Header Parameters**

- `Authorization`: _String_ - Bearer token for your organization.

---

##### Example Response

Returns an array of all loaded trust sources and their current state.

```json
[
  {
    "sourceId": "austria-tsl",
    "sourceFamily": "TSL",
    "displayName": "TSL AT (seq 72)",
    "sourceUrl": "https://www.signatur.rtr.at/currenttl.xml",
    "territory": "AT",
    "issueDate": "2026-03-11T15:17:42Z",
    "nextUpdate": "2026-09-11T14:17:42Z",
    "sequenceNumber": "72",
    "authenticityState": "VALIDATED",
    "freshnessState": "FRESH",
    "metadata": {
      "tslVersion": "5",
      "signerSubjectDN": "CN=Trusted List 9,OU=Fachbereich Telekommunikation und Post,O=Rundfunk und Telekom Regulierungs-GmbH,C=AT",
      "signerIssuerDN": "CN=RTR Services 5,O=Rundfunk und Telekom Regulierungs-GmbH,C=AT",
      "signerSerialNumber": "312100091138082272680184838882066682156716496761"
    }
  },
  {
    "sourceId": "ewc-pilot",
    "sourceFamily": "TSL",
    "displayName": "TSL TT (seq 1)",
    "sourceUrl": "https://ewc-consortium.github.io/ewc-trust-list/EWC-TL",
    "territory": "TT",
    "issueDate": "2025-02-13T01:00:00Z",
    "nextUpdate": "2025-08-13T00:00:00Z",
    "sequenceNumber": "1",
    "authenticityState": "SKIPPED_DEMO",
    "freshnessState": "EXPIRED",
    "metadata": {
      "tslVersion": "5"
    }
  }
]
```

**Response Fields**

- `sourceId`: _String_ - The identifier assigned when the source was loaded.
- `sourceFamily`: _String_ - The format of the trust list. One of `TSL` (ETSI TS 119 612 XML), `LOTE` (ETSI TS 119 602 JSON or XML), or `PILOT`. Detected automatically from the content.
- `displayName`: _String_ - A human-readable label derived from the list content. For TSL sources: `"TSL {territory} (seq {sequenceNumber})"`. For LoTE sources: the `listId` from the list's own metadata.
- `sourceUrl`: _String (nullable)_ - The URL the list was fetched from. Null when the source was loaded from inline content and no `sourceUrl` was provided in the request body.
- `territory`: _String (nullable)_ - The ISO country or territory code taken from the list's own scheme information. Null for LoTE sources that do not declare a territory.
- `issueDate`: _String (nullable)_ - ISO 8601 timestamp from the list's own metadata indicating when the list was issued.
- `nextUpdate`: _String (nullable)_ - ISO 8601 timestamp from the list's own metadata indicating when the list is expected to be updated. Drives the `freshnessState` calculation. Null when the list does not declare a next-update date.
- `sequenceNumber`: _String (nullable)_ - The revision counter from the list's own metadata. Null when the list does not declare a sequence number.
- `authenticityState`: _String_ - Result of XMLDSig signature validation. One of:
  - `VALIDATED` — signature was present and passed validation.
  - `FAILED` — signature was present but failed validation.
  - `SKIPPED_DEMO` — validation was skipped because `validateSignature: false` was used, or the list is unsigned and signature is not required.
  - `UNKNOWN` — authenticity state could not be determined.
- `freshnessState`: _String_ - Staleness of the list, computed against `nextUpdate` at load time. One of:
  - `FRESH` — current time is before `nextUpdate`.
  - `STALE` — current time is within 24 hours of `nextUpdate`.
  - `EXPIRED` — current time is past `nextUpdate`.
  - `UNKNOWN` — `nextUpdate` was not present in the list.
- `metadata`: _Object_ - Source-family-specific key/value pairs extracted from the list. For TSL sources: always includes `tslVersion`; includes `signerSubjectDN`, `signerIssuerDN`, and `signerSerialNumber` when signature validation was performed. For LoTE JSON sources: includes `listType` when present in the list metadata.

| Status | Description |
|--------|-------------|
| `200` | Sources retrieved successfully |

## Refresh a Trust Source

Re-fetch and re-parse a previously loaded trust source to pick up updates from the origin URL. Trust sources are persisted to the database and survive service restarts, but the content is not updated automatically — use this endpoint to refresh on demand.

**Option: CURL**

**Endpoint:** `POST /v1/{target}/trust-registry-api/sources/{sourceId}/refresh` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Trust%20Registry/post_v1__target__trust_registry_api_sources__sourceId__refresh)

##### Example Request

```bash
curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/trust-registry-api/sources/{sourceId}/refresh' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'
```

**Path Parameters**

- `orgID`: _String_ - Your organization's Base URL prefix.
- `target`: _String_ - The Trust Registry service path.
- `sourceId`: _String_ - The ID of the trust source to refresh.

**Header Parameters**

- `Authorization`: _String_ - Bearer token for your organization.

---

##### Example Response

```json
{
  "sourceId": "ewc-pilot",
  "success": true,
  "entitiesLoaded": 19,
  "servicesLoaded": 29,
  "identitiesLoaded": 38
}
```

If the source cannot be re-fetched (e.g. the origin URL is unreachable), the response is still `200` but with `success: false`:

```json
{
  "sourceId": "ewc-pilot",
  "success": false,
  "error": "Failed to fetch from https://ewc-consortium.github.io/ewc-trust-list/EWC-TL: Connection timed out"
}
```

| Status | Description |
|--------|-------------|
| `200` | Request processed — check `success` field in the response body |
| `422` | Refresh failed at the trust list parsing level |