Skip to main content
Credential definitions

Create credential definition

POST/v4/config/ows/issuer/credential-definitions

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.

  • Signing key: send cryptographicKeyFormat and cryptographicKeyIdentifier in each configuration, because each configuration has its own credentialCategory and its key must fit it. The issuer refuses a key at the top level. The key must be an active key of the organisation with a certificate chain. The answer gives the key of the first configuration at the top level: it signs the codes and tokens of the issuer for this definition. The issuer compares the certificate of each key with the credentialCategory of its configuration and shows the result in signingKeyCheck. It does not refuse a key that does not fit.
  • Card images: without display.logo.uri and display.backgroundImage.uri, the definition and each configuration get the logo and cover image of the organisation. Upload your own with Update credential definition logo image and Update credential definition cover image.
  • Claims: give them in each configuration (claims, or credentialDefinition for jwt_vc_json), or as a credentialDefinitionUri. List credential definition templates has ready claims for common credentials.
  • PID: a configuration whose type is a PID (vct in the urn:eudi:pid: namespace, or doctype eu.europa.ec.eudi.pid.1) lists every mandatory attribute of PID Rulebook v1.7 and marks it mandatory, in the format of its type; the issuer refuses any other PID definition with 400.

The answer (HTTP 200) is the new credential definition with definitionVersion 1. Then issue it with Issue credential.

Authorizations

  • Authorizationstringheaderrequired

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

    Scope:credential-definitions:create

Body

application/json

The credential definition. label, version and credentialConfigurations are required. The issuer refuses a member that it does not know (HTTP 400).

  • labelstringrequired

    Your name for the credential definition, 3 to 100 characters. Wallets do not show it. The platform reserves the labels Payment User Credential, Payment Card Credential, Payment Account Credential, PID Issuance and Photo ID Issuance (in any case).

    3 to 100 characters.

    Example:"Issue Portable Document A1"

  • credentialConfigurationsobject[]required

    The credential configurations, at least one. version, requiresTrustedWalletProvider and acceptedWalletProviders are top-level members: in an entry they give 400 (unknown field). A configuration member (for example credentialFormat or claims) belongs in an entry: at the top level the issuer checks its type and does not use it.

    At least 1 item.

  • versionenum<string>required

    The OpenID4VCI version of the issuance: version_01 (OpenID4VCI 1.0). Required: a request without it (version: required) or with another value (version: invalid value <value>) gets HTTP 400. It never changes after the create.

    Available options:version_01

    Example:"version_01"

  • requiresTrustedWalletProviderboolean

    true: the wallet must send a valid wallet unit attestation, else the issuer refuses the request with invalid_client at the pushed authorization request, the interactive authorization, the token request, the refresh and the wallet-initiated path. A trust source of acceptedWalletProviders must have the signer of the wallet unit attestation and of each key attestation of a wallet provider as wallet_provider, else the issuer refuses the token or credential request with invalid_client (Client attestation refused: the wallet provider of the attestation is not trusted for this credential). false: no trust check runs: the recorded value is not_required. A wallet unit attestation that a wallet sends has only its validity checked, and an invalid one is recorded and does not refuse. Default false.

  • acceptedWalletProvidersstring (uuid)[]

    The trust sources that the wallet provider must come from (their id, from List trust sources), each used for wallet_provider. Required when requiresTrustedWalletProvider is true (trust.accepted_list_required). The value stays when the switch is false. Default [].

  • requiresInteractiveAuthorisationboolean

    true: the issuance uses the Interactive Authorization Endpoint (credential issuer identifier v1.0-iar). Needed for a dynamic credential request (presentationDefinitionId of the issue call). Default false.

  • externalOpenidProviderIdstring | null

    An external OpenID provider of the organisation that authenticates the holder in the Authorization Code Flow. Another value gives HTTP 400. Leave it out, or send null, for no provider.

  • allowsWalletInitiatedIssuanceboolean

    true: a wallet can start an issuance without a credential offer, with a pushed authorisation request that names a scope or a credential configuration id. The issuer then makes the issuance history. Default false.

  • allowsCredentialOfferReuseboolean

    true: one credential offer can start one issuance for each wallet. A pushed authorisation request with the issuer_state of an offer that is already in use starts a new issuance history, until the issuer_state expires. false: one credential offer serves one wallet. Default false.

  • displayobject

    The display of the credential definition. Without logo.uri and backgroundImage.uri, the issuer puts the logo and cover image of the organisation (or of the sandbox organisation). To upload your own images, use the logo and cover image calls of the credential definition after the create.

Response

application/json

The new credential definition. The status is 200, not 201.

  • credentialDefinitionobject

    The new credential definition, with its configurations and their signing key checks.