Skip to main content

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.

​
Why trust is a separate concept

Every other concept in these docs, DIDs, credentials, formats, templates, is about how information moves. Trust is about whether to believe it. A credential with a perfectly valid signature still tells you nothing useful until you decide whether the issuer was allowed to make that statement in the first place. The cryptography proves the signature is real; it does not prove the signer is the university, the government, or the regulator it claims to be. That’s your call, expressed through the Trusted Entities API.

​
Trust anchors on didx:me

A Trusted Entity on didx:me is a named bundle of issuer identifiers that a verifier is willing to accept. You attach Trusted Entities to individual credentials within a presentation template (up to 20 trusted entities per credential). Each Trusted Entity contains one or more of:

Issuer DIDs

Decentralized Identifiers belonging to the issuer. Used to anchor trust for SD-JWT VC credentials. did:web is the method didx:me currently uses.

x509 certificates

Signing certificates issued to the issuer through a Certificate Signing Request (CSR). Used to anchor trust for mDoc credentials. A root certificate transitively trusts all certificates it has signed, so a single root can anchor an entire ecosystem.
When a presentation request is sent, the trusted DIDs and the Subject Key Identifiers of trusted X.509 certificates travel with the request to the holder’s wallet. The wallet uses them to pre-filter candidate credentials before the holder is even shown a consent prompt — credentials that can’t satisfy the trust requirements never appear as options.

​
The default you need to know about

A presentation template with no trusted entities attached will accept credentials from any issuer. This is the platform default. Always attach at least one trusted entity to each credential in a presentation template before going to production, otherwise a valid signature from any issuer will pass verification, even issuers you have never heard of.
Once a trusted entity is linked, the rule is strict: the credential’s issuer must match one of the identifiers in the trusted-entity bundle and the cryptographic signature must be valid. If either side fails, verification fails.

​
A concrete example

Say you’re a car rental company and you want to verify Mobile Driver’s Licences. Your verifier needs to accept mDLs only from legitimate government issuers, not from whoever decides to spin up an issuing service. Without a Trusted Entity: 
Verifier accepts mDL → signature valid → verification passes → 🚨
Anyone who stands up a service with a valid signing certificate can issue “mDLs” that your verifier accepts. With a Trusted Entity containing the actual government DIDs or certs: 
Verifier accepts mDL → issuer matches trusted bundle? → signature valid? → verification passes
                            ↓ No                              ↓ No
                            rejected                          rejected
This is why the Trusted Entities and Certificates API groups matter even though they don’t appear in the basic issuer or verifier walkthroughs. You will encounter them as soon as you move past the sandbox.

​
Operational implications

  • Trusted Entities are attached to individual credentials within a presentation template, not to the template as a whole. A single template can require a trusted DMV for a driving-licence credential and a trusted employer for an employment credential.
  • Rotating an issuer’s signing key or certificate means updating the Trusted Entity that references it. Plan for this.
  • The link between a trusted entity and a credential within a presentation template is part of the template payload. See the Trusted Entities and Presentation Templates operations under the Credentials (Issuer + Verifier) section of the API Reference for current request and response shapes.