Trusted Entities

Trusted Entities in Paradym enable you to define the issuers you trust. Trusted entities can be linked to a specific credential that is requested in a presentation template, and limit who can issue a specific credential.

On a trusted entity, two types of certificates and identifiers can be configured:

X.509 certificates. This can be either a signing certificate, or a root certificate, and is supported for SD-JWT VC, and mDOC credentials.
Decentralized Identifiers (DIDs). This is supported for SD-JWT VC and Anoncreds credentials using the did:cheqd:testnet, did:cheqd:mainnet and did:web method.

When using a root certificate (instead of a signing certificate) for a trusted entity, all certificates that are signed (either directly or indirectly) by the root certificate are valid. This means that a single root certificate, could be enough to configure the trusted entitities for a whole ecosystem.

An example could be the European Union (EU) that creates a root certificate, and uses that root certificate to sign over a certificate for each EU member state. However another approach could be that each country manages it’s own root certificate, in which case you’d need to add up to 27 root certificates.

In the future integration with specific identity ecosystems will be simplified by providing pre-populated trusted entities that can be linked to a presentation template.

Creating a Trusted Entity

When creating a trusted entity, you need to provide the following information:

The name of the trusted entity, allowing you to recognize the trusted entity in the API and dashboard.
The DIDs and X.509 certificates to link to the trusted entity. Both DIDs and X.509 certificates can be combined in a single trusted entity, with a limit of 20 DIDs and X.509 certificates each. X.509 certificates must be provided in PEM format.

To obtain the DIDs and X.509 certificates for a trusted entity is dependent on which credentials you want to verify:

If you want to verify credentials issued by a project you own or have access to, you can extract the DIDs for that project under the “My Identifiers” section of the “Trust” tab in the dashboard.
If you want to verify credentials from a project you don’t have acces to, or is not issued by Paradym, obtaining the needed DIDs or X.509 certificates can differ. If you’re unsure, ask the issuer of the credential where the DIDs and X.509 certificates can be found.

Once you have the needed X.509 certificates and DIDs, you can use the API or dashboard to create a trusted entity in Paradym.

To create a trusted entity from the API, make a POST request to https://api.paradym.id/v1/projects/{projectId}/trusted-entities. See the API Reference for detailed usage information.


{
  "id": "clu6p64z80001a5muhvp2uvpy",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "name": "Trustland Government",
  "certificates": [
    {
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIBnjCCAUSgAwIBAgIQN/SO2htOoQyFZubYJVKcujAKBggqhkjOPQQDAjAdMQsw\nCQYDVQQGEwJOTDEOMAwGA1UEAxMFQW5pbW8wHhcNNzAwMTAxMDAwMDAwWhcNMjUx\nMTIyMDgyMjEyWjAdMQswCQYDVQQGEwJOTDEOMAwGA1UEAxMFQW5pbW8wOTATBgcq\nhkjOPQIBBggqhkjOPQMBBwMiAALcD1XzKepFxWMAOqV+ln1fybBt7DRO5CV0f9A6\nmRp2xaOBhTCBgjAqBgNVHQ4EIwQhAtwPVfMp6kXFYwA6pX6WfV/JsG3sNE7kJXR/\n0DqZGnbFMAsGA1UdDwQEAwIChDAsBgNVHSMEJTAjgCEC3A9V8ynqRcVjADqlfpZ9\nX8mwbew0TuQldH/QOpkadsUwGQYDVR0RBBIwEIIOZnVua2UuYW5pbW8uaWQwCgYI\nKoZIzj0EAwIDSAAwRQIgPdbgy3gL/8BFFkMCoeDGLYt5BAMKZhqg19krQgmbBDAC\nIQCPJ08ouPoTyUsQ0hYGemoC2nrvOj1N//WYvj5TRoC5Dw==\n-----END CERTIFICATE-----",
      "name": "Root certificate"
    }
  ],
  "dids": [
    {
      "name": "Main DID",
      "did": "did:web:metadata:paradym.id:423fa790-dad5-46e3-99a7-07c340e10b60"
    }
  ]
}

Linking a trusted entity to a presentation template

To use a trusted entity, it must first be linked to a presentation template. Each credential within a presentation template can have up to 20 trusted entities linked to it.

A presentation template that has no trusted entities configured will accept ANY issuer, so it is recommended to always link a trusted entity to the credential within a presentation template.

Once a trusted entity is linked to a credential within a presentation template, only the X.509 certificates and DIDs from that trusted entity will be accepted as issuers of that credential.

The DIDs configured on trusted entities will be sent in the request to the wallet, meaning the wallet can already filter out credentials that do not match the DID of the trusted entity. For X.509 certificates this is not possible and matching can only be performed after the presentation is received. This means there is a higher chance of a wallet submitting a presentation that does not meet your trust requirements.

To link a trusted entity to a presentation template from the API, you can provide a list of trustedEntities for each credential in a presentation template. There’s two methods to link a trusted entity in the API:

Create a new presentation template by making a POST request to https://api.paradym.id/v1/projects/{projectId}/templates/presentations. See the API Reference for detailed usage information.
Update an existing presentation template by making a PUT request to https://api.paradym.id/v1/projects/{projectId}/templates/presentations/{presentationTemplateId}. See the API Reference for detailed usage information.


{
  "name": "Car rental",
  "description": "To rent a car you need to present your drivers license",
  "credentials": [
    {
      "name": "Drivers License",
      "format": "mdoc",
      "type": "org.iso.18013.5.1.mDL",
      "trustedIssuers": ["cm7rz7u83000l11o9bfnk4x0l"],
      "attributes": {
        "org.iso.18013.5.1": {
          "properties": {
            "given_name": {
              "intentToRetain": false
            },
            "family_name": {
              "intentToRetain": false
            }
          }
        }
      }
    }
  ]
}