Skip to main content

Update credential definition

PUT 

/v2/config/digital-wallet/openid/sdjwt/credential-definition/:credentialDefinitionId

Updates an existing credential definition. The changes apply to future credential issuances that use this definition. This operation replaces the whole credentialDefinitions array, so always send every credential configuration that the issuer must keep. Set credentialDefinitions[].id to the identifier of an existing configuration to change it, and omit the field to add a new one. The issuer always discards display.logo.uri and display.backgroundImage.uri from the request body and keeps the stored images; use the update logo image and update cover image operations to change the artwork. version does not change. You can change the signing key with cryptographicKeyFormat and cryptographicKeyIdentifier.

Request​

Path Parameters

    credentialDefinitionId stringrequired

    Unique identifier of the credential definition that specifies the credential format, type, and claims structure for OID4VCI issuance.

Body

required

New values for the credential definition. Every field is optional except credentialDefinitions. When label is present, it must contain 3 to 100 characters.

    label string

    Possible values: >= 3 characters and <= 100 characters

    Human-readable label describing the intended use of this credential definition (e.g. 'Issue Portable Document A1'). When you supply the field, the value must contain 3 to 100 characters. The issuer keeps the current label when you omit the field. The labels Payment User Credential, Payment Card Credential, Payment Account Credential, PID Issuance and Photo ID Issuance are reserved for the platform.

    credentialDefinitions object[]required

    Possible values: >= 1

    Credential configurations of this credential definition, as the complete new list. Set id on an entry, with the same credentialFormat, to change a configuration that the issuer already published: the configuration keeps its id. An entry without id, or with another credentialFormat, is a new configuration. Leave an existing configuration out of the array to remove it. When an entry with id leaves out expirationInDays and expirationInSeconds, the configuration keeps its validity. Put each configuration field inside its entry: the issuer ignores a configuration field at the top level.

    cryptographicKeyFormat string

    Possible values: [x509, did:key]

    Format of the new key of the credential definition: x509 or did:key. Leave it out to keep the current key.

    cryptographicKeyIdentifier string

    Identifier of the new key of the credential definition, from Key Management. Leave it out to keep the current key.

    enforceWUA boolean

    When true, the issuer requires the holder to present a valid Wallet Unit Attestation (WUA) during the OID4VCI credential issuance flow, as defined in the EUDI Wallet Architecture Reference Framework. A value that you leave out becomes false, so send it on each update.

    supportCredentialOfferReuse boolean

    When true, one credential offer can start an issuance for more than one wallet until the offer expires. Leave it out to keep the stored value.

    supportInteractiveAuthorisationEndpoint boolean

    When true, the issuer publishes an interactive authorisation endpoint for this credential definition.

    display object

    Default display properties for every credential configuration of this credential definition. The issuer always discards logo.uri and backgroundImage.uri from this object and keeps the stored values, whether you send them or not. To change the artwork, use the update logo image and update cover image operations.

    name string

    Display name for the credential in wallet UIs.

    description string

    Human-readable description of the credential purpose.

    backgroundColor string

    Hex colour code for the credential card background (e.g. #FFFFFF).

    textColor string

    Hex colour code for text on the credential card (e.g. #000000).

    logo object

    Logo image of the credential card. The issuer discards uri and keeps the stored image.

    uri string

    URL of the logo image. The issuer ignores this field on update.

    altText string

    Alternative text for the logo image.

    backgroundImage object

    Background image of the credential card. The issuer discards uri and keeps the stored image.

    uri string

    URL of the background image. The issuer ignores this field on update.

Responses​

The issuer updated the credential definition and published the new credential configurations in the OID4VCI Credential Issuer Metadata.

Schema
    credentialDefinition object

    Credential definition record as stored by the issuer. The top level fields hold the settings of the whole record, and credentialDefinitions holds one entry for each credential configuration that the issuer publishes in the OID4VCI Credential Issuer Metadata.

    id stringrequired

    Identifier of the credential definition. This field holds the same value as credentialDefinitionId.

    credentialDefinitionId stringrequired

    Unique identifier assigned to the credential definition upon creation. Use this ID to reference the credential definition in OpenID for Verifiable Credentials Issuance (OID4VCI) operations.

    openIdOrganisationId stringrequired

    Identifier of the OpenID wallet deployment that holds this credential definition.

    createdAt numberrequired

    Unix timestamp (in seconds) indicating when this credential definition was created.

    updatedAt numberrequired

    Unix timestamp (in seconds) indicating when this credential definition was last modified.

    label stringrequired

    Human-readable label describing the intended use of this credential definition (e.g. 'Issue Portable Document A1').

    credentialDefinitions object[]

    Credential configurations of this credential definition. The issuer publishes each entry as a separate credential configuration in the OID4VCI Credential Issuer Metadata. The value is null for a record that holds no configuration.

  • Array [
  • id string

    Unique identifier of this credential configuration. The issuer generates the value. Use it in the credentials[].id field of the issue credential request, and in the credentialDefinitions[].id field of an update credential definition request.

    credentialConfigurationId string

    Identifier of the credential configuration as published in the OID4VCI Credential Issuer Metadata. The wallet uses this value to request this credential configuration during the issuance flow.

    label string

    Human-readable label describing the intended use of this credential configuration.

    expirationInDays integer

    Validity of the issued credential, in days.

    expirationInSeconds integer

    Validity of the issued credential, in seconds, when the configuration has one. It has precedence over expirationInDays.

    supportRevocation boolean

    When true, the issuer supports revocation of credentials from this configuration.

    revocationMethod string

    Possible values: [status_list]

    Method used for credential revocation. status_list is the IETF Token Status List.

    statusListCryptographicKeyFormat string

    Possible values: [x509, did:key]

    Format of the key that signs the status lists of this configuration, when the configuration names one.

    statusListCryptographicKeyIdentifier string

    Identifier of the key that signs the status lists of this configuration, when the configuration names one. Without it, the key that signs the credentials signs the status lists.

    enforceCredentialUniqueness boolean

    When true, each credential under this configuration is unique per holder.

    supportCredentialReissuance boolean

    When true, holders can request reissuance of expired or near-expiry credentials.

    credentialBindingMethods string[]

    Possible values: [did:key, jwk, cose_key]

    Holder key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. cose_key is valid only for the mso_mdoc format. [] means that the credential is not bound to a holder key.

    authorizationRequestType string

    Possible values: [authorization_details, scope_based]

    authorization_details (the default) or scope_based. With scope_based, the issuer accepts only the Authorization Code Flow for this credential definition.

    scope string

    OAuth 2.0 scope value of this credential configuration. The default is the credential configuration id. A wallet can ask for the configuration by this scope or by authorization_details.

    display object

    Display properties for the credential card in wallet UIs.

    name string

    Display name for the credential in wallet UIs.

    locale string

    BCP47 language tag for the display properties. The issuer always sets en-GB, and ignores any locale that you send.

    description string

    Human-readable description of the credential purpose.

    backgroundColor string

    Hex colour code for the credential card background (e.g. #FFFFFF).

    textColor string

    Hex colour code for text on the credential card (e.g. #000000).

    logo object

    Logo image of the credential card.

    uri string

    URL of the logo image.

    altText string

    Alternative text for the logo image.

    backgroundImage object

    Background image of the credential card.

    uri string

    URL of the background image.

    credentialResponseInterval number

    Minimum polling interval (in seconds) for the wallet when using the OID4VCI Deferred Credential Endpoint.

    credentialFormat string

    Possible values: [jwt_vc_json, dc+sd-jwt, mso_mdoc]

    Credential format of this configuration. jwt_vc_json is W3C VC (JWT). dc+sd-jwt is IETF SD-JWT VC. mso_mdoc is ISO 18013-5 mDoc/mDL.

    validationPath string

    JSONPath expression that selects the part of the credential payload that the issuer validates against the claims. The value is $.vc for jwt_vc_json, and $ for dc+sd-jwt and mso_mdoc.

    type string[]

    Credential type strings. The issuer sets this field when credentialFormat is jwt_vc_json. These values appear in the type field of the issued W3C VC (JWT).

    vct string

    Verifiable Credential Type identifier. The issuer sets this field when credentialFormat is dc+sd-jwt (e.g. urn:eu.europa.ec.eudi:pid:1).

    doctype string

    Document type identifier. The issuer sets this field when credentialFormat is mso_mdoc (e.g. org.iso.18013.5.1.lpid).

    credentialDefinitionUri string

    URL of the external claims schema that the issuer used to build the claims of this configuration.

    cryptographicKeyFormat string

    Possible values: [x509, did:key]

    Format of the key that signs the credentials of this configuration: x509 or did:key. A configuration that named no key holds the key of the credential definition.

    cryptographicKeyIdentifier string

    Identifier of the key that signs the credentials of this configuration.

    credentialCategory object

    The id of a credential category (the list credential categories operation): the eIDAS category of a credential configuration. none (no certificate rule), pid (person identification data), eaa (non-qualified attestation), qeaa (qualified attestation) or pub-eaa (attestation issued by or for a public sector body).

    signingKeyCheck object

    The check of the signing key of a credential configuration, made at the time of the answer. It covers two rules: the certificate of the key fits the credential category of the configuration, and the key of an mDL (doctype org.iso.18013.5.1.mDL) has the ISO/IEC 18013-5 Document Signer profile. The save of a credential definition uses the same check, so the result is the result that a save gives now. The result does-not-fit does not stop issuance.

    result stringrequired

    Possible values: [fits, does-not-fit, exempt, not-checked]

    The result of the check: fits, does-not-fit, exempt or not-checked. fits: the certificate of the signing key fits the rules. does-not-fit: the certificate does not fit a rule, for example because the certificate chain of the key changed after the save. Select another key, or request a certificate with the presetId of the category (for an mDL, the preset mdoc-document-signer). exempt: the certificate does not fit, but the key has an exemption (trustedListExemption of the key: the certificate is in a trusted list), so the save does not refuse it. not-checked: the category is none and the configuration is not an mDL, so no rule applies.

    messages string[]required

    The texts of the check, one for each rule that the key does not fit, with the fix (the category rule first, then the mDL rule). An empty list for fits. For exempt, first Exempt: listed in <list> as <service>, then the rules. For not-checked, an empty list, or an information text when the key has a PID certificate and the configuration does not issue a PID.

    suggestedCredentialCategory stringnullable

    Possible values: [pid, null]

    pid when credentialCategory is none, the vct or the doctype is a PID (urn:eudi:pid:1, urn:eu.europa.ec.eudi:pid:1, eu.europa.ec.eudi.pid.1), and the signing key fits pid. Set the category with an update. null in all other cases.

    supportAttestationProof boolean

    When true, the issuer accepts an attestation proof (key attestation).

    supportJwtProof boolean

    When true, the issuer accepts a jwt proof of possession (OpenID4VCI 1.0 proof_types_supported).

    enforceKeyAttestation boolean

    When true, the issuer refuses an issuance without a valid key attestation.

    keyAttestationsRequired object

    Object specifying key attestation requirements per proof type supported by the Credential Issuer.

    attestation object

    Key attestation requirements for the 'attestation' proof type.

    key_storage string[]

    Possible values: [iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate, iso_18045_high]

    Accepted key storage security levels (e.g., ISO/IEC 18045 basic).

    user_authentication string[]

    Possible values: [iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate, iso_18045_high]

    Accepted user authentication security levels.

    jwt object

    Key attestation requirements for the 'jwt' proof type.

    key_storage string[]

    Possible values: [iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate, iso_18045_high]

    Accepted key storage security levels.

    user_authentication string[]

    Possible values: [iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate, iso_18045_high]

    Accepted user authentication security levels.

    claims object

    Claims of the credential, as claim path pointers. The issuer sets this field when credentialFormat is dc+sd-jwt or mso_mdoc.

    claims object[]

    One claim path pointer for each claim that the issuer publishes.

  • Array [
  • path undefined[]

    Claim path pointer that selects the claim in the credential payload. Each element is a string for an object key, an integer for an array index, or null for every element of an array. For mso_mdoc, the first element is the mDoc namespace.

    mandatory boolean

    When true, the issuer always includes the claim.

    limitDisclosure boolean

    When true, the holder can disclose the claim selectively.

  • ]
  • credentialDefinition object

    Claims of the credential, as claim path pointers. The issuer sets this field when credentialFormat is jwt_vc_json. Each path starts with credentialSubject.

    claims object[]

    One claim path pointer for each claim that the issuer publishes.

  • Array [
  • path undefined[]

    Claim path pointer that selects the claim below $.vc. The first element is credentialSubject.

    mandatory boolean

    When true, the issuer always includes the claim.

  • ]
  • ]
  • version stringrequired

    Version of the OpenID for Verifiable Credential Issuance (OID4VCI) specification that the issuer uses for the issuance flow. version_01 is OpenID4VCI 1.0. A record that you created with an earlier version of this API can hold another value. The issuer sets the value at creation time and never changes it.

    cryptographicKeyFormat string

    Possible values: [x509, did:key]

    Format of the key of the credential definition: x509 or did:key.

    cryptographicKeyIdentifier string

    Identifier of the key of the credential definition, from Key Management. A configuration that names no key of its own signs with this key.

    trustAnchor stringrequired

    Copy of cryptographicKeyFormat.

    kid stringrequired

    Copy of cryptographicKeyIdentifier.

    enforceWUA booleanrequired

    When true, the issuer requires the holder to present a valid Wallet Unit Attestation (WUA) during the OID4VCI issuance flow.

    supportInteractiveAuthorisationEndpoint booleanrequired

    When true, the issuer publishes an interactive authorisation endpoint for this credential definition.

    supportWalletInitiatedIssuance boolean

    When true, a wallet can start the issuance with a pushed authorisation request that names a scope or a credential configuration id.

    supportCredentialOfferReuse boolean

    When true, one credential offer can start an issuance for more than one wallet until the offer expires.

    oidcProviderId string

    Identifier of the external OpenID provider that authenticates the end user in the Authorization Code Flow. Empty when the credential definition has none.

    systemManaged booleanrequired

    When true, the platform made and manages this credential definition, for example for an extension.

    extensionEnabled booleanrequired

    When true, an extension supplies the credential data for this credential definition.

    display objectrequired

    Display properties of the credential, as published in the OID4VCI Credential Issuer Metadata. Wallets use these values to draw the credential card.

    name stringrequired

    Display name for the credential shown in wallet UIs, as specified in the OID4VCI Credential Issuer Metadata.

    locale stringrequired

    BCP47 language tag for the display properties. The issuer always sets en-GB, and ignores any locale that you send.

    description stringrequired

    Human-readable description of the credential purpose.

    backgroundColor stringrequired

    Hex colour code for the credential card background (e.g. #FFFFFF).

    textColor stringrequired

    Hex colour code for text on the credential card (e.g. #000000).

    logo objectrequired

    Logo image shown on the credential card. The issuer sets the organisation logo when you do not supply a URI. The issuer always returns the object, and uri is empty when the credential definition holds no logo.

    uri stringrequired

    URL of the logo image.

    altText stringrequired

    Alternative text for the logo image. Wallets use this text for accessibility.

    backgroundImage objectrequired

    Background image of the credential card. The issuer sets the organisation cover image when you do not supply a URI. The issuer always returns the object, and uri is empty when the credential definition holds no background image.

    uri stringrequired

    URL of the background image.

    expirationInDays integerrequired

    Validity of the first credential configuration, in days. Each entry of credentialDefinitions holds its own validity.

    expirationInSeconds integer

    Validity of the first credential configuration, in seconds, when it has one. The issuer leaves the field out when it has no value.

    supportRevocation booleanrequired

    When true, the issuer supports revocation of credentials from this credential definition.

    revocationMethod stringrequired

    Possible values: [status_list]

    Method used for credential revocation. status_list is the IETF Token Status List.

    enforceCredentialUniqueness booleanrequired

    When true, each credential issued under this definition is unique per holder.

    supportCredentialReissuance booleanrequired

    When true, holders can request reissuance of expired or near-expiry credentials.

    credentialBindingMethods string[]

    Possible values: [did:key, jwk, cose_key]

    Holder key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. cose_key is valid only for the mso_mdoc format. The value is null when the record holds no binding method.

    credentialFormat stringrequired

    Possible values: [jwt_vc_json, dc+sd-jwt, mso_mdoc]

    Credential format identifier as defined in OID4VCI. Supported formats: jwt_vc_json (W3C VC JWT), dc+sd-jwt (IETF SD-JWT VC), mso_mdoc (ISO 18013-5 mDoc/mDL).

    validationPath stringrequired

    JSONPath expression that selects the part of the credential payload that the issuer validates against the claims. The value is $.vc for jwt_vc_json, and $ for dc+sd-jwt and mso_mdoc.

    type string[]

    Credential type strings as defined in the OID4VCI specification. These values appear in the type field of the issued W3C VC (JWT). The issuer omits this field when the record uses another credential format.

    vct string

    Verifiable Credential Type identifier used when credentialFormat is dc+sd-jwt. Included in the vct claim of the issued IETF SD-JWT VC.

    doctype string

    Document type identifier used when credentialFormat is mso_mdoc. Identifies the credential in the ISO 18013-5 mDoc/mDL format (e.g. org.iso.18013.5.1.lpid).

    namespace stringrequired

    Namespace identifier for ISO 18013-5 mDoc/mDL credentials. The value is empty for an OpenID4VCI 1.0 credential definition, because the mDoc namespace is the first element of each claim path.

    credentialDefinitionUri stringrequired

    URL of the external claims schema that the issuer used to build the claims of this record.

    claims object

    Claims of the credential, as claim path pointers. The issuer sets this field when credentialFormat is dc+sd-jwt or mso_mdoc.

    claims object[]

    One claim path pointer for each claim that the issuer publishes.

  • Array [
  • path undefined[]

    Claim path pointer that selects the claim in the credential payload. Each element is a string for an object key, an integer for an array index, or null for every element of an array. For mso_mdoc, the first element is the mDoc namespace.

    mandatory boolean

    When true, the issuer always includes the claim.

    limitDisclosure boolean

    When true, the holder can disclose the claim selectively.

  • ]
  • supportJwtProof boolean

    When true, the issuer accepts a jwt proof of possession.

    supportAttestationProof boolean

    When true, the issuer accepts an attestation proof (key attestation).

    enforceKeyAttestation boolean

    When true, the issuer refuses an issuance without a valid key attestation.

    credentialDefinition object

    Claims of the credential, as claim path pointers. The issuer sets this field when credentialFormat is jwt_vc_json. Each path starts with credentialSubject.

    claims object[]

    One claim path pointer for each claim that the issuer publishes.

  • Array [
  • path undefined[]

    Claim path pointer that selects the claim below $.vc. The first element is credentialSubject.

    mandatory boolean

    When true, the issuer always includes the claim.

  • ]
Loading...