Keys

Read key usage

GET/v4/config/ows/key-management/keys/{keyId}/usage

Shows where a key is in use, whether Delete key can retire it (canDelete), and what signs with its certificate chain, so whether Delete certificate chain can remove the chain (certificateChainUses, canDeleteCertificateChain). Check it before you retire a key or change its certificate chain.

The report lists the credential definitions and presentation definitions that sign with the key and the status lists of those credential definitions, last changed first. It counts the uses by the signed issuer metadata and the wallet provider configurations, and the issuances and verifications in progress. It covers the organisation and its sandbox organisations (a sandbox organisation signs with the keys of its main organisation), the same scope as the retirement check. With search, the lists and their counts keep only the matching definitions and the status lists of the kept credential definitions; the other members always cover every use. A retired key gives 404, and so does the wallet key of the organisation while it has no certificate chain.

Read key usage

Language of the request sample

curl 'https://demo-api.igrant.io/v4/config/ows/key-management/keys/{keyId}/usage' \
  -H 'Authorization: ApiKey <your-api-key>'

{
  "keyId": "dc40eda5e357445aa13ed33014fa2608",
  "hasCertificates": true,
  "credentialDefinitions": {
    "count": 1,
    "items": [
      {
        "id": "b0c28543-ac18-4fc3-b606-a08380ec9e60",
        "label": "OpenID Conformance - PID (SD-JWT)"
      }
    ]
  },
  "presentationDefinitions": {
    "count": 0,
    "items": []
  },
  "statusLists": {
    "count": 1,
    "items": [
      {
        "id": "2bcdc957-ac7d-457d-ac95-73287c72b41f",
        "credentialConfigurationId": "b0c28543-ac18-4fc3-b606-a08380ec9e60",
        "issuerUrl": "https://demo-api.igrant.io/organisation/60905277-d953-4ef7-aa4c-cec413d00d93/service/version-01"
      }
    ]
  },
  "signedIssuerMetadata": {
    "count": 0
  },
  "walletProviderConfigurations": {
    "count": 0
  },
  "issuanceRecordsInFlight": {
    "count": 22
  },
  "verificationRecordsInFlight": {
    "count": 0
  },
  "canDelete": false,
  "systemManagedDefinitions": 1,
  "canDeleteCertificateChain": false,
  "certificateChainUses": {
    "credentialDefinitions": 1,
    "presentationDefinitions": 0,
    "statusLists": 0,
    "signedIssuerMetadata": 0,
    "walletProviderConfigurations": 0
  }
}

Authorizations

Authorizationstringheaderrequired
Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.
Scope:keys:read

Path parameters

keyIdstringrequired
The keyId of a key of the organisation, from List keys or from the answer of Create key. It is also the kid of its JWK.

Query parameters

searchstring
Keeps the credential and presentation definitions whose name or ID contains the text, and the status lists of the kept credential definitions. Case insensitive; an ID also matches without its hyphens. At most 128 characters. The other counts and canDelete always cover every use of the key.
At most 128 characters.

Response

application/json

The usage report of the key.

keyIdstring
The key ID.
Example:"3f2a91c47b8d4e6fa0c5d7e18b924f30"
hasCertificatesboolean
true when the key has a certificate chain.
Example:true
credentialDefinitionsobject
The credential definitions that sign with the key (one of their configurations or the definition itself).
presentationDefinitionsobject
The presentation definitions that sign their requests with the key.
statusListsobject
The status lists that sign with the key.
signedIssuerMetadataobject
The issuer configurations that sign their credential issuer metadata with the key.
walletProviderConfigurationsobject
The wallet provider configurations that sign their attestations with the key.
issuanceRecordsInFlightobject
The issuance histories in progress that sign with the key.
verificationRecordsInFlightobject
The verifications in progress that sign with the key.
canDeleteboolean
true when nothing uses the key, so Delete key can retire it. Always false for the wallet key of the organisation, which is never deleted. Always computed over every use, also with search.
Example:false
systemManagedDefinitionsinteger
The number of the credential definitions and presentation definitions that sign with the key and that the platform manages (a definition of an extension or of a Passwordless Login client). Always computed over every use, also with search.
Example:1
certificateChainUsesobject
The uses that sign with the certificate chain of the key (the uses with cryptographicKeyFormat x509). Always computed over every use, also with search.
canDeleteCertificateChainboolean
true when no use signs with the certificate chain, so Delete certificate chain can remove it. With false, that call gives 409 certificate.chain_in_use.
Example:false