Look up a key in the trust lists

POST 
/v2/config/digital-wallet/openid/key-management/trust-lookup

Checks whether the trust sources of the organisation know a signing key: the trust list lookup service of the platform, the trust lists of the organisation, and the X.509 CAs of its trust authorities. Use it before you select a key for a credential definition or a presentation definition. The dashboard shows the same result in Trust List Lookup.

Give the key ID in kid and the key format in format. With x509, the wallet looks up the certificate chain of the key. With a DID format, give the DID of the key in did. The answer has the result of each source in sources, the best entry in selected, and verified when that entry is granted and its certificates are valid.

Access: an organisation admin token, or an API key with the scope trust-anchors:read (an older API key: config).

Request

application/json

Body

required

The key and the key format to look up.

kid stringrequired

The key ID of a key of the organisation.

format stringrequired

The key format to look up. x509 (the key needs a certificate chain), a DID format such as did:key (give did), or kid.

did string

The DID of the key. Required for a DID format, and it must be of that format.

Responses

200

The service returned the result of each trust source.

Response Headers

application/json

Schema

Schema

kid stringrequired

The key ID of the request.

format stringrequired

The key format of the lookup.

query objectrequired

What the wallet looks up. x5c for the x509 format (the certificate chain of the key), did for a DID format, kid for the kid format.

property name* any

What the wallet looks up. x5c for the x509 format (the certificate chain of the key), did for a DID format, kid for the kid format.

verified booleanrequired

Shows true when the selected entry has the status granted and valid certificates.

selected objectnullable

One entry of a trust source that matches the key: the trust service and its provider, as the source gives them.

status string

The status of the trust service, for example granted. Other values, such as withdrawn, mean that the source does not trust the key now.

matchType string

How the key matched the entry, for example fingerprint (the certificate itself), public_key, ski or chain (a chain to a listed CA).

certificateValid boolean

Shows true when the certificates of the key are valid now.

trustList object

The trust list of the entry.

property name* any

The trust list of the entry.

provider object

The trust service provider of the entry, as the trust list gives it.

property name* any

The trust service provider of the entry, as the trust list gives it.

service object

The trust service of the entry, as the trust list gives it, for example serviceName, serviceTypeIdentifier and serviceStatus.

property name* any

The trust service of the entry, as the trust list gives it, for example serviceName, serviceTypeIdentifier and serviceStatus.

certificateDetails object[]

The subject, the issuer and the validity of each certificate of the key that the entry matched.

property name* any

One entry of a trust source that matches the key: the trust service and its provider, as the source gives them.

sources object[]required
The answer of each trust source, in this order: the trust list lookup service of the platform, the trust lists of the organisation, and the X.509 CAs of its trust authorities. Each source has name, kind (lookup, ETSI_TL, ETSI_TL_JSON or X509_CA), url (null for an X.509 CA), matched, the matching entries, and error. A source that cannot answer gives its reason in error; the request still succeeds.
Array [
name stringrequired
kind stringrequired
Possible values: [lookup, ETSI_TL, ETSI_TL_JSON, X509_CA]
url stringnullablerequired
matched booleanrequired
entries object[]required
Array [
status string
The status of the trust service, for example granted. Other values, such as withdrawn, mean that the source does not trust the key now.
matchType string
How the key matched the entry, for example fingerprint (the certificate itself), public_key, ski or chain (a chain to a listed CA).
certificateValid boolean
Shows true when the certificates of the key are valid now.
trustList object
The trust list of the entry.
property name* any
The trust list of the entry.
provider object
The trust service provider of the entry, as the trust list gives it.
property name* any
The trust service provider of the entry, as the trust list gives it.
service object
The trust service of the entry, as the trust list gives it, for example serviceName, serviceTypeIdentifier and serviceStatus.
property name* any
The trust service of the entry, as the trust list gives it, for example serviceName, serviceTypeIdentifier and serviceStatus.
certificateDetails object[]
The subject, the issuer and the validity of each certificate of the key that the entry matched.
]
error stringnullablerequired
]

Example (from schema)

{
  "kid": "3f2a91c47b8d4e6fa0c5d7e18b924f30",
  "format": "x509",
  "query": {},
  "verified": true,
  "selected": {
    "status": "granted",
    "matchType": "string",
    "certificateValid": true,
    "trustList": {},
    "provider": {},
    "service": {},
    "certificateDetails": [
      {}
    ]
  },
  "sources": [
    {
      "name": "NordXDataspace Trust List",
      "kind": "lookup",
      "url": "string",
      "matched": true,
      "entries": [
        {
          "status": "granted",
          "matchType": "string",
          "certificateValid": true,
          "trustList": {},
          "provider": {},
          "service": {},
          "certificateDetails": [
            {}
          ]
        }
      ],
      "error": "string"
    }
  ]
}

Example

{
  "kid": "3f2a91c47b8d4e6fa0c5d7e18b924f30",
  "format": "x509",
  "query": {
    "x5c": [
      "MIIC..."
    ]
  },
  "verified": true,
  "selected": {
    "status": "granted",
    "matchType": "fingerprint",
    "certificateValid": true,
    "trustList": {
      "name": "eaa-providers.xml",
      "url": "https://tl.example.com/eaa-providers.xml"
    },
    "provider": {
      "tSPName": "Example Organisation AB"
    },
    "service": {
      "serviceName": "Example Organisation EAA issuance",
      "serviceStatus": "granted"
    },
    "certificateDetails": [
      {
        "subject": "CN=Example Organisation Attestation Provider,O=Example Organisation AB,C=SE",
        "issuer": "CN=Example CA,O=Example CA AB,C=SE",
        "notValidBefore": "2026-01-01T00:00:00",
        "notValidAfter": "2027-01-01T00:00:00"
      }
    ]
  },
  "sources": [
    {
      "name": "NordXDataspace Trust List",
      "kind": "lookup",
      "url": "https://trust.example.com/lookup",
      "matched": false,
      "entries": [],
      "error": null
    },
    {
      "name": "eaa-providers.xml",
      "kind": "ETSI_TL",
      "url": "https://tl.example.com/eaa-providers.xml",
      "matched": true,
      "entries": [
        {
          "status": "granted",
          "matchType": "fingerprint",
          "certificateValid": true
        }
      ],
      "error": null
    }
  ]
}

400

The request is not valid: no body, a missing kid or format, an unknown member, an unknown key (Key <kid> not found), a key format that the wallet does not support, x509 for a key without a certificate chain (The key has no certificate chain. Upload a certificate chain for the key, or select another key format.), or a DID format without did or with a did of another format.

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

401

Unauthorized

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

500

Internal server error

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

Loading...