Skip to main content

Credential definitions

Create and maintain the credential definitions that the issuer offers: their credential configurations, their versions, and their logo and cover images.

Create credential definition

Creates a credential definition: what the organisation issues, and how. Each entry of `credentialConfigurations` is one credential configuration (one format and one `vct`, `doctype` or `type`, with its claims, validity, revocation and holder binding). The issuer publishes each configuration in the Credential Issuer Metadata at once, with a `credentialConfigurationId` that it makes. The top level has the settings of the whole definition: the label, the trust in wallets and the issuance options.

List credential definitions

Lists the credential definitions of the organisation, newest first, one page at a time. Each item is the credential definition as [Read credential definition](/docs/openid4vc-api/config-read-digital-wallet-open-id-credential-definition) gives it (without `definitionVersion`), with `issuanceCount`, the number of its issuance histories. For the counts in buckets, use [Read credential definition statistics](/docs/openid4vc-api/config-read-credential-definition-statistics). To read the next page, send the `nextCursor` of the answer as `cursor`. The list leaves out the deleted credential definitions.

Read credential definition

Returns one credential definition with its credential configurations: for each, the format, the claims, the validity, the revocation, the holder binding and the signing key. Each configuration also has the check of its signing key at the time of the read (`signingKeyCheck`), so you see when a key does not fit its credential category. `definitionVersion` is the current version; read an earlier version with [Read credential definition version](/docs/openid4vc-api/config-read-credential-definition-version).

Delete credential definition

Deletes a credential definition: its credential configurations leave the Credential Issuer Metadata, and you can no longer issue it. The issuance history calls and the statistics of the organisation then leave out its issuance histories. The delete does not revoke the credentials that the issuer already gave: to make them invalid, [revoke](/docs/openid4vc-api/config-update-digital-wallet-open-id-credential-revocation-status) their issuance histories before you delete the definition.

Preview credential definition from URI

Fetches the JSON document at a URI and returns it, so that you can look at it before you use the URI as `credentialDefinitionUri` of a credential configuration. The issuer reads the document as a JSON Schema: it resolves the `$ref` members, removes the `$defs` members and checks the result against JSON Schema draft 2020-12. It does not check claims path pointers: the create and update calls do that with the document of a `credentialDefinitionUri`, which must be a claims path pointer document (`{'claims': [{'path': [...]}]}`). The URI must be a public HTTP or HTTPS URL; the issuer waits 10 seconds at most.

Read credential definition version

Returns a credential definition as it was in one version. Each create and update of a credential definition makes a new version, and a version never changes. An issuance history follows the version that it started with (`credentialDefinition.definitionVersion` of [Read issuance history](/docs/openid4vc-api/config-read-digital-wallet-open-id-credential-history)): use this call to see the settings that governed it. The answer has the shape of [Read credential definition](/docs/openid4vc-api/config-read-digital-wallet-open-id-credential-definition), without the checks of the signing keys.

Update credential definition logo image

Uploads the logo of a credential definition. The platform stores the image and sets `display.logo.uri` of the definition and of each of its credential configurations to the public URL of the image, so the Credential Issuer Metadata shows it at once. The image must be PNG, JPEG, GIF or WebP, at most 5 MiB and 4096 x 4096 pixels (the default limits). [Update credential definition](/docs/openid4vc-api/config-update-digital-wallet-open-id-credential-definition) cannot change the image.

Update credential definition cover image

Uploads the cover image (the card background) of a credential definition. The platform stores the image and sets `display.backgroundImage.uri` of the definition and of each of its credential configurations to the public URL of the image, so the Credential Issuer Metadata shows it at once. The image must be PNG, JPEG, GIF or WebP, at most 5 MiB and 4096 x 4096 pixels (the default limits). [Update credential definition](/docs/openid4vc-api/config-update-digital-wallet-open-id-credential-definition) cannot change the image.

Upload image

Uploads an image and returns its public URL (`imageUrl`). Put the URL in a display image of a credential definition (`display.logo.uri` or `display.backgroundImage.uri`) when you create or update the definition. Anybody can read the image at the URL with [Read image](/docs/openid4vc-api/config-read-digital-wallet-open-id-image), and the image stays: there is no delete. The image must be PNG, JPEG, GIF or WebP, at most 5 MiB and 4096 x 4096 pixels (the default limits). To set the logo or cover image of a stored credential definition in one call, use [Update credential definition logo image](/docs/openid4vc-api/config-update-digital-wallet-open-id-credential-logo-image).