> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Trusted entities (advanced)

> Tenant-scoped records of issuers your verifier trusts. The building block referenced by custom presentation templates.

<Note>
  **You only need this page if you're using custom presentation templates.** With presets, trust is described in
  real-world terms (DIDs, x509 certs) directly inside the preset, and the platform handles tenant-side records for you.
  Custom templates work at a lower level: they reference your tenant's own **trusted-entity records** by id, which you
  create and manage with the API on this page.
</Note>

## What a trusted entity is

A **trusted entity** is a named bundle of issuer identifiers (DIDs and/or x509 certificates), registered in your tenant under a single record id. It says: "*from now on, when a template references entity `ent-acme`, it means any of these issuers*".

```json theme={null}
{
  "id": "cm7d9cq5600pwk3zq3kmpg8uc",
  "name": "Trusted Government Issuers",
  "dids": [{ "did": "did:web:sarb.gov.za", "name": "South African Reserve Bank" }],
  "certificates": [
    {
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIUJ8vK...truncated...PFvKkQ==\n-----END CERTIFICATE-----",
      "name": "Department of Home Affairs"
    }
  ]
}
```

The id (`cm7d9cq5600pwk3zq3kmpg8uc` here) is **scoped to your tenant**. It's not portable, not visible to other tenants, and only meaningful inside your own templates.

## Two abstraction levels for trust

didx:me lets you express which issuers count as proof at two levels:

* **In a preset (the default).** List issuers as **real-world identifiers** directly: `{ kind: "did", did: "did:web:..." }` or `{ kind: "x509", certificate: "-----BEGIN..." }`. Presets are tenant-portable, so they can't reference any tenant's record ids. When a tenant uses the preset, the platform resolves each entry against that tenant's own trusted-entity records (reusing existing ones or creating new ones as needed).
* **In a custom presentation template.** List issuers as an array of **trusted-entity record ids** (`["ent-alpha", "ent-beta"]`). The records have to exist in your tenant first. Using them directly is the explicit, lower-level path; presets work at a higher level and consumers of a preset don't need to manage records themselves.

If a preset fits your verification, prefer it. See [Presentation presets](/products/didx-me/guides/verifiers/presentation-presets-intro). Use trusted entities directly only when you need a custom template (e.g. to combine credential types in a way no preset offers, or because you trust issuers that no published preset covers).

## Create a trusted entity

```bash theme={null}
curl -X POST "https://test.didxtech.com/me-creds/api/v1/trusted-entities" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trusted Government Issuers",
    "dids": [
      { "did": "did:web:sarb.gov.za", "name": "South African Reserve Bank" }
    ],
    "certificates": [
      { "certificate": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIUJ8vK...truncated...PFvKkQ==\n-----END CERTIFICATE-----", "name": "Department of Home Affairs" }
    ]
  }'
```

### Request fields

#### `name`

Your label for this bundle. Visible only inside your tenant. Choose something operational ("Trusted Government Issuers", "SARB Test Environment") rather than a marketing name. The wallet doesn't show this; it shows the per-identifier `name` instead.

#### `dids`

A list of DID-based issuers. Each entry is `{ did, name }`:

* `did`. The DID the issuer publishes (e.g. `did:web:sarb.gov.za`).
* `name`. The human-readable label the wallet shows end users during consent. Choose a name an end user will recognise: "Department of Home Affairs", not "doha-prod-1".

#### `certificates`

A list of x509-certificate-based issuers, for issuers that operate via a traditional PKI chain (common for ISO 18013-5 mDLs). Each entry is `{ certificate, name }`:

* `certificate`. PEM-encoded certificate, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` framing.
* `name`. Same wallet-visible label rule as for DIDs.

A trusted entity can include both `dids` and `certificates`, or only one. At least one identifier must be supplied; an empty bundle trusts nothing.

### Response

**HTTP 201 Created.** The response includes the assigned `id`. **Capture this:** it's what you'll pass to `trustedIssuers` in a custom presentation template.

## List, fetch, update, delete

| Operation   | Endpoint                                        |
| ----------- | ----------------------------------------------- |
| List        | `GET /me-creds/api/v1/trusted-entities`         |
| Fetch by id | `GET /me-creds/api/v1/trusted-entities/{id}`    |
| Update      | `PUT /me-creds/api/v1/trusted-entities/{id}`    |
| Delete      | `DELETE /me-creds/api/v1/trusted-entities/{id}` |

Updates replace the bundle entirely with the new payload. Deletes are forbidden if the entity is still referenced by a presentation template; remove or update the template's `trustedIssuers` first.

See the [Trusted Entities API reference](/products/didx-me/api-reference/v1/me-creds#tag/trusted-entities) for full request/response schemas.

## Lifecycle

* **Key rotation.** When an issuer rotates a signing key or certificate, update the trusted-entity record with the new identifier (and optionally remove the old one once you've stopped accepting credentials signed under it).
* **Onboarding new issuers.** Add new entries to an existing entity, or create a new entity if it represents a logically distinct trust group.
* **Removing trust.** Remove the relevant DID or certificate from the entity. Any pending verifications using the old identifier start failing.