Trusted Entities

Trusted Entities in Paradym enable you to define the issuers and wallets you trust. Trusted entities can be linked to a specific credential in a presentation template to limit who can issue a credential, or to a credential template to limit which wallets can receive a credential (see Trusted wallets).

Every DID, certificate and LoTE on a trusted entity has a type, which is either issuer (the default) or wallet. Issuer entries are used to trust the issuer of a credential during verification, wallet entries are used to trust the wallet during issuance. For LoTEs the type is detected automatically from the LoTE profile (the EU Wallet Providers List is a wallet, all other lists are issuer) and cannot be overridden. If you provide a type that conflicts with the detected one, the request is rejected.

On a trusted entity, three 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.
• ETSI Lists of Trusted Entities (LoTEs). A LoTE is a signed list of trusted entities published as part of the EUDI Trust Framework. Paradym can fetch and validate LoTEs, automatically extracting both the issuance certificates (trusted to issue the credential) and the revocation certificates (trusted to sign the credential’s status list) they contain.

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 wallet you own or have access to, you can extract the DIDs for that wallet under the My Identifiers  section of the “Trust” tab in the dashboard. Similarly, you can extract the root certificate used for signing (issuerRoot) under the My Certificates  section of the “Trust” tab.
• If you want to verify credentials from a wallet you don’t have access 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.

{
  "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"
    }
  ],
  "etsiLotes": [
    {
      "url": "https://lote.example.eu/pid-providers",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----"
    },
    {
      "url": "https://lote.example.eu/pubeaa-providers",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----",
      "credentialTypes": {
        "mdoc": [
          "eu.europa.ec.eudi.pubeaa.custom.1"
        ],
        "sd-jwt-vc": [
          "urn:eudi:pubeaa:custom:1",
          {
            "type": "startsWith",
            "value": "urn:eudi:pubeaa:custom:"
          }
        ]
      }
    }
  ]
}

Restricting certificates and DIDs to credential types

By default an issuer certificate or DID is trusted for every credential type. When one ecosystem signs different credentials under different roots or DIDs, you can restrict each with credentialTypes, so that a credential is only accepted when it comes from a certificate or DID trusted for its type. Without this, a trusted entity holding both a PID root and an attestation root would also accept a PID signed under the attestation root.

credentialTypes uses the same format as for ETSI LoTEs: matchers keyed by credential format, each either an exact type or a starts-with prefix. Once set, a format that is left out is not trusted at all. Certificates accept the sd-jwt-vc and mdoc formats, and DIDs accept sd-jwt-vc and anoncreds (matched on the schema id). Credential types can only be set on entries with type issuer.

{
  "name": "Trustland",
  "certificates": [
    {
      "name": "PID root",
      "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      "credentialTypes": {
        "mdoc": ["eu.europa.ec.eudi.pid.1"],
        "sd-jwt-vc": [{ "type": "startsWith", "value": "urn:eudi:pid:" }]
      }
    },
    {
      "name": "Attestation root",
      "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      "credentialTypes": { "mdoc": ["eu.europa.ec.av.1"] }
    }
  ]
}

In the dashboard, add the credential types under Credential Types on the certificate or DID. Leave the list empty to trust it for every credential type.

ETSI Lists of Trusted Entities

An ETSI LoTE is a digitally signed list of trusted entities, published as part of the European Digital Identity (EUDI) trust framework. Instead of manually adding individual X.509 certificates for each trusted entity, you can point to a LoTE URL and Paradym will automatically fetch the list, verify its signature, and extract the certificates it contains. Currently, Paradym supports LoTEs up to a maximum size of 1MB.

For each trusted entity in the list, Paradym extracts the certificates from both its Issuance services (trusted to issue the credential) and its Revocation services (trusted to sign the credential’s revocation status list). This means a credential issued by a LoTE-listed provider whose status list is signed by a separate revocation authority — as long as both are published in the same LoTE — is verified correctly, including its revocation status.

This is especially useful for EU ecosystems where a single LoTE can cover all authorized issuers for a given credential type, such as national PID providers or mDL providers. Paradym supports the following LoTE types

For LoTE types with known credential types (the EU PID Providers List and mDL Providers List), the credential types are assigned automatically and cannot be customized. The EU PID Providers List covers any SD-JWT VC type within the urn:eudi:pid: namespace, so country-specific PID types such as Germany’s urn:eudi:pid:de:1 are matched automatically. For other LoTE types (e.g. the EU Public EAA Providers List) you configure the credential types the LoTE applies to via credentialTypes.

Paradym validates a LoTE against the EU profile of its type in ETSI TS 119 602 . A list is also accepted when its policy or legal notice has another format, or its services have a status. A service with a status other than notified is not trusted. The scheme territory must be EU, so national lists such as the German ones are only available as common trusted entities.

Each configured credential type can be either an exact match or a starts-with match. A starts-with matcher covers every credential type sharing the given prefix — useful for namespaces where multiple types are registered (such as country-specific PID types within the urn:eudi:pid: namespace). In the API, an exact match is a plain string ("urn:eudi:pubeaa:custom:1") and a starts-with match is an object ({ "type": "startsWith", "value": "urn:eudi:pubeaa:custom:" }). In the dashboard, choose Exact or Starts with from the dropdown next to each credential type when configuring a LoTE on a trusted entity.

On the Free tier, for example after downgrading from a paid tier, verification ignores the LoTEs of your trusted entities. A trusted entity that also has certificates or DIDs keeps trusting those. A credential whose trusted entities only trust issuers through LoTEs can no longer be requested.

Automatic updates

Paradym automatically keeps LoTEs up to date by re-fetching and validating the LoTE daily. If a LoTE cannot be fetched or validated, the wallet owner will receive an email notification and Paradym will retry the next day.

After 3 repeated failures, the LoTE will be automatically disabled, and the wallet owner will receive an email notification. A disabled LoTE will no longer be taken into account during credential verification. A disabled LoTE can be re-enabled by updating the trusted entity with corrected configuration.

Common trusted entities

Setting up an ecosystem yourself means collecting its issuer certificates or trust lists and keeping them current. For a number of common ecosystems Paradym does that for you, and publishes them as common trusted entities. You link one to a presentation template exactly like your own, using its id, and Paradym keeps the underlying certificates and trust lists up to date.

Common trusted entities have stable, readable ids that are the same in every wallet and in every Paradym deployment:

They cannot be created, changed or deleted, and they do not count towards the trusted entities of your wallet. In the dashboard they are listed under Common trusted entities on the Trusted Entities  page, where you can inspect the certificates and trust lists they contain, and they are selectable in the trusted issuers picker of a presentation template.

To retrieve the available common trusted entities from the API, make a GET request to https://api.paradym.id/v1/wallets/{walletId}/trusted-entities/common. It supports the same search[name] and cursor pagination as the trusted entities list . To use one, pass its id in trustedIssuers on a presentation template credential, alongside (or instead of) the ids of your own trusted entities:

{
  "credentials": [
    {
      "format": "mdoc",
      "type": "eu.europa.ec.eudi.pid.1",
      "trustedIssuers": ["german-eudi-wallet-sandbox"],
      "attributes": {}
    }
  ]
}

A common trusted entity can only be linked to a credential it can trust an issuer of, based on the formats and credential types its certificates, DIDs and trust lists apply to. For example, an entity whose certificates are limited to the mdoc PID is rejected for an SD-JWT VC credential.

To use EUDI lists of trusted entities (LoTEs) defined in common trusted entities, you must be on a paid tier. On the Free tier, verification ignores them, so a common trusted entity that only has LoTEs trusts no issuer.

Trust list availability

Paradym fetches and verifies the trust lists of common trusted entities daily. Each list in the API response has an enabled field, and an issuedAt field with the issue date the publisher put in the version Paradym currently uses. The dashboard shows the same on the entity’s page.

If a list cannot be fetched or verified 4 days in a row, it is no longer used for verification and the entities it lists are not trusted. Paradym keeps retrying daily and uses the list again as soon as it verifies, so there is nothing for you to fix. A disabled list is skipped, like a disabled LoTE on your own trusted entities, and the credential is still verified against the other trusted entities. Only when nothing trusted is left for the credential does creating a verification request fail, with an error naming the affected entity. Certificate-based entities (such as France Identité) do not depend on a list and are always available.

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 and Subject Key Identifier (SKI) / Authority Key Identifier (SKI) of X509 certificates 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 or X509 certificate of a trusted entity.

{
  "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
            }
          }
        }
      }
    }
  ]
}

Trusted wallets

Where trusted issuers limit who can issue a credential, trusted wallets limit which wallets can receive a credential during issuance. This is enforced using OpenID4VCI wallet attestations : the wallet presents an attestation signed by its wallet provider, and Paradym only continues the issuance if that provider is one of the configured trusted wallets.

Trusted wallets are configured on a credential template and are supported for SD-JWT VC and mDoc credentials. They use the wallet-typed DIDs, X.509 certificates and (EU Wallet Providers List) LoTEs of the linked trusted entities.

When no trusted wallets are configured on a credential template, any wallet can receive the credential (the current default). A wallet attestation sent by the wallet is then ignored, so an invalid attestation does not block issuance. When one or more are configured, a wallet attestation is required and must be signed by one of the trusted wallet providers, otherwise issuance is rejected.

A linked trusted entity must contain at least one wallet-typed entry (a wallet DID, a wallet certificate, or an EU Wallet Providers List LoTE). Linking a trusted entity that has no wallet entries is rejected — both when saving the credential template and when creating an issuance offer — so that a template can never silently accept any wallet while appearing to be restricted.

When a credential is restricted to trusted wallets and also uses an Authorization Server, the wallet is already trusted through its attestation, so the Authorization Server’s redirect URI allow-list is not enforced for that issuance.

To link trusted wallets to a credential template, provide a list of trusted entity ids in the trustedWallets field when creating or updating an SD-JWT VC or mDoc credential template, or select them from the Trusted Wallets section of the credential template editor in the dashboard.

When retrieving a credential template, the linked trusted entities are only returned when you request them with the ?include=trustedWallets query parameter (mirroring ?include=credentials.trustedIssuers on presentation templates). Without it, the trustedWallets field is omitted from the response.

Key attestations

Trusted wallets let you trust the wallet provider. Key attestations go a step further and let you require assurance about the key a credential is bound to. Using OpenID4VCI key attestations , the wallet provider signs an attestation describing how the key is protected and Paradym only issues the credential if the attestation meets your requirements.

Because the key attestation is verified against the same trust anchor as the wallet attestation, key attestations build directly on trusted wallets: you can only require key attestations on a credential template that has at least one trusted wallet configured. Setting keyAttestations without any trustedWallets is rejected.

Add a keyAttestations object to an SD-JWT VC or mDoc credential template. Its presence means a key attestation is required. Both level lists are optional:

{
  "trustedWallets": ["<trusted-entity-id>"],
  "keyAttestations": {
    "keyStorage": ["iso_18045_high"],
    "userAuthentication": ["iso_18045_moderate"]
  }
}

• Omit keyAttestations entirely to not require a key attestation (the default).
• Use an empty object ("keyAttestations": {}) to require a key attestation without constraining the levels.
• keyStorage is the required attack potential resistance of the key storage, and userAuthentication the required resistance of the user authentication methods allowed to access the key. Both are lists of ISO 18045 levels : iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate or iso_18045_high.

The levels are compared hierarchically, so an attested level that is stronger than or equal to a required level satisfies it (for example, an attested iso_18045_high satisfies a required iso_18045_moderate). A requirement is met if any attested value reaches any required value. If the attestation is missing, or does not reach a required level, issuance is rejected.

In the dashboard, configure this in the Key Attestation section of the credential template editor: enable Require Key Attestation and optionally pick the key storage and user authentication levels.

Paradym accepts a key attestation via either OpenID4VCI proof mechanism: the jwt proof type with the key attestation embedded in its header (the wallet signs a proof of possession with the attested key), or the standalone attestation proof type (the key attestation is presented on its own, without a proof of possession). The wallet decides which to use, and both are verified against your trusted wallets.