Skip to main content
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.

​
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”. This is a stored record, trimmed. The full response also carries createdAt and updatedAt. You supply name, plus any dids and certificates; the platform assigns the id:
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. Use trusted entities directly only when you need a custom template, either to combine credential types in a way no preset offers, or because you trust issuers that no published preset covers.

​
Create a trusted entity

​
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, such as 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

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 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.