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
Unique identifier of the credential definition that specifies the credential format, type, and claims structure for OID4VCI issuance.
- application/json
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.
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.
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.
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.
Identifier of the new key of the credential definition, from Key Management. Leave it out to keep the current key.
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.
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.
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.
Display name for the credential in wallet UIs.
Human-readable description of the credential purpose.
Hex colour code for the credential card background (e.g. #FFFFFF).
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.
URL of the logo image. The issuer ignores this field on update.
Alternative text for the logo image.
backgroundImage object
Background image of the credential card. The issuer discards uri and keeps the stored image.
URL of the background image. The issuer ignores this field on update.
Responses
- 200
- 400
- 401
- 500
The issuer updated the credential definition and published the new credential configurations in the OID4VCI Credential Issuer Metadata.
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- Array [
- ]
- Array [
- ]
- ]
- Array [
- ]
- Array [
- ]
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.
Identifier of the credential definition. This field holds the same value as credentialDefinitionId.
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.
Identifier of the OpenID wallet deployment that holds this credential definition.
Unix timestamp (in seconds) indicating when this credential definition was created.
Unix timestamp (in seconds) indicating when this credential definition was last modified.
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.
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.
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.
Human-readable label describing the intended use of this credential configuration.
Validity of the issued credential, in days.
Validity of the issued credential, in seconds, when the configuration has one. It has precedence over expirationInDays.
When true, the issuer supports revocation of credentials from this configuration.
Possible values: [status_list]
Method used for credential revocation. status_list is the IETF Token Status List.
Possible values: [x509, did:key]
Format of the key that signs the status lists of this configuration, when the configuration names one.
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.
When true, each credential under this configuration is unique per holder.
When true, holders can request reissuance of expired or near-expiry credentials.
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.
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.
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.
Display name for the credential in wallet UIs.
BCP47 language tag for the display properties. The issuer always sets en-GB, and ignores any locale that you send.
Human-readable description of the credential purpose.
Hex colour code for the credential card background (e.g. #FFFFFF).
Hex colour code for text on the credential card (e.g. #000000).
logo object
Logo image of the credential card.
URL of the logo image.
Alternative text for the logo image.
backgroundImage object
Background image of the credential card.
URL of the background image.
Minimum polling interval (in seconds) for the wallet when using the OID4VCI Deferred Credential Endpoint.
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.
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.
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).
Verifiable Credential Type identifier. The issuer sets this field when credentialFormat is dc+sd-jwt (e.g. urn:eu.europa.ec.eudi:pid:1).
Document type identifier. The issuer sets this field when credentialFormat is mso_mdoc (e.g. org.iso.18013.5.1.lpid).
URL of the external claims schema that the issuer used to build the claims of this configuration.
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.
Identifier of the key that signs the credentials of this configuration.
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.
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.
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.
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.
When true, the issuer accepts an attestation proof (key attestation).
When true, the issuer accepts a jwt proof of possession (OpenID4VCI 1.0 proof_types_supported).
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.
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).
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.
Possible values: [iso_18045_basic, iso_18045_enhanced-basic, iso_18045_moderate, iso_18045_high]
Accepted key storage security levels.
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.
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.
When true, the issuer always includes the claim.
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.
Claim path pointer that selects the claim below $.vc. The first element is credentialSubject.
When true, the issuer always includes the claim.
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.
Possible values: [x509, did:key]
Format of the key of the credential definition: x509 or did:key.
Identifier of the key of the credential definition, from Key Management. A configuration that names no key of its own signs with this key.
Copy of cryptographicKeyFormat.
Copy of cryptographicKeyIdentifier.
When true, the issuer requires the holder to present a valid Wallet Unit Attestation (WUA) during the OID4VCI issuance flow.
When true, the issuer publishes an interactive authorisation endpoint for this credential definition.
When true, a wallet can start the issuance with a pushed authorisation request that names a scope or a credential configuration id.
When true, one credential offer can start an issuance for more than one wallet until the offer expires.
Identifier of the external OpenID provider that authenticates the end user in the Authorization Code Flow. Empty when the credential definition has none.
When true, the platform made and manages this credential definition, for example for an extension.
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.
Display name for the credential shown in wallet UIs, as specified in the OID4VCI Credential Issuer Metadata.
BCP47 language tag for the display properties. The issuer always sets en-GB, and ignores any locale that you send.
Human-readable description of the credential purpose.
Hex colour code for the credential card background (e.g. #FFFFFF).
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.
URL of the logo image.
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.
URL of the background image.
Validity of the first credential configuration, in days. Each entry of credentialDefinitions holds its own validity.
Validity of the first credential configuration, in seconds, when it has one. The issuer leaves the field out when it has no value.
When true, the issuer supports revocation of credentials from this credential definition.
Possible values: [status_list]
Method used for credential revocation. status_list is the IETF Token Status List.
When true, each credential issued under this definition is unique per holder.
When true, holders can request reissuance of expired or near-expiry credentials.
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.
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).
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.
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.
Verifiable Credential Type identifier used when credentialFormat is dc+sd-jwt. Included in the vct claim of the issued IETF SD-JWT VC.
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 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.
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.
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.
When true, the issuer always includes the claim.
When true, the holder can disclose the claim selectively.
When true, the issuer accepts a jwt proof of possession.
When true, the issuer accepts an attestation proof (key attestation).
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.
Claim path pointer that selects the claim below $.vc. The first element is credentialSubject.
When true, the issuer always includes the claim.
{
"credentialDefinition": {
"id": "9f1c2a34-5b6d-4e7f-8a90-1b2c3d4e5f60",
"credentialDefinitionId": "9f1c2a34-5b6d-4e7f-8a90-1b2c3d4e5f60",
"openIdOrganisationId": "string",
"createdAt": 1750000000,
"updatedAt": 1750000600,
"label": "Issue Portable Document A1",
"credentialDefinitions": [
{
"id": "string",
"credentialConfigurationId": "string",
"label": "string",
"expirationInDays": 0,
"expirationInSeconds": 0,
"supportRevocation": true,
"revocationMethod": "status_list",
"statusListCryptographicKeyFormat": "x509",
"statusListCryptographicKeyIdentifier": "string",
"enforceCredentialUniqueness": true,
"supportCredentialReissuance": true,
"credentialBindingMethods": [
"did:key"
],
"authorizationRequestType": "authorization_details",
"scope": "string",
"display": {
"name": "string",
"locale": "en-GB",
"description": "string",
"backgroundColor": "string",
"textColor": "string",
"logo": {
"uri": "string",
"altText": "string"
},
"backgroundImage": {
"uri": "string"
}
},
"credentialResponseInterval": 0,
"credentialFormat": "jwt_vc_json",
"validationPath": "string",
"type": [
"string"
],
"vct": "string",
"doctype": "string",
"credentialDefinitionUri": "string",
"cryptographicKeyFormat": "x509",
"cryptographicKeyIdentifier": "string",
"credentialCategory": "eaa",
"signingKeyCheck": {
"result": "fits",
"messages": []
},
"suggestedCredentialCategory": null,
"supportAttestationProof": true,
"supportJwtProof": true,
"enforceKeyAttestation": true,
"keyAttestationsRequired": {
"attestation": {
"key_storage": [
"iso_18045_basic"
],
"user_authentication": [
"iso_18045_basic"
]
},
"jwt": {
"key_storage": [
"iso_18045_basic"
],
"user_authentication": [
"iso_18045_basic"
]
}
},
"claims": {
"claims": [
{
"path": [
"address",
"country"
],
"mandatory": true,
"limitDisclosure": true
}
]
},
"credentialDefinition": {
"claims": [
{
"path": [
"credentialSubject",
"identifier"
],
"mandatory": true
}
]
}
}
],
"version": "version_01",
"cryptographicKeyFormat": "x509",
"cryptographicKeyIdentifier": "string",
"trustAnchor": "string",
"kid": "string",
"enforceWUA": true,
"supportInteractiveAuthorisationEndpoint": true,
"supportWalletInitiatedIssuance": true,
"supportCredentialOfferReuse": true,
"oidcProviderId": "string",
"systemManaged": true,
"extensionEnabled": true,
"display": {
"name": "Legal Person Identification Data",
"locale": "en-GB",
"description": "string",
"backgroundColor": "#FFFFFF",
"textColor": "#000000",
"logo": {
"uri": "string",
"altText": "string"
},
"backgroundImage": {
"uri": "string"
}
},
"expirationInDays": 180,
"expirationInSeconds": 0,
"supportRevocation": true,
"revocationMethod": "status_list",
"enforceCredentialUniqueness": true,
"supportCredentialReissuance": true,
"credentialBindingMethods": [
"did:key"
],
"credentialFormat": "jwt_vc_json",
"validationPath": "string",
"type": [
"string"
],
"vct": "urn:eu.europa.ec.eudi:pid:1",
"doctype": "eu.europa.ec.eudi.pid.1",
"namespace": "string",
"credentialDefinitionUri": "string",
"claims": {
"claims": [
{
"path": [
"address",
"country"
],
"mandatory": true,
"limitDisclosure": true
}
]
},
"supportJwtProof": true,
"supportAttestationProof": true,
"enforceKeyAttestation": true,
"credentialDefinition": {
"claims": [
{
"path": [
"credentialSubject",
"identifier"
],
"mandatory": true
}
]
}
}
}
The request is invalid. The issuer returns this status when no credential definition matches credentialDefinitionId (Failed to get credential definition by id: <id>), when the request body is not valid JSON, when label has fewer than 3 or more than 100 characters or uses a reserved platform value, when credentialBindingMethods holds cose_key for a credential format other than mso_mdoc, when an entry has an unknown member, when a validity is outside its range, when the key of an mso_mdoc entry is not x509, when credentialCategory is not a category id, when an entry with the category eaa, qeaa or pub-eaa has a claim at the place of the EAA category of ETSI TS 119 472-1 (errorType eaa_category_claim_reserved), or when the claims fail validation. When the certificate of the signing key of an entry does not fit its credentialCategory, or the key of an mDL entry has no ISO/IEC 18013-5 Document Signer profile, the answer has errorType signing_key_does_not_fit and errorField credentialDefinitions[<index>].cryptographicKeyIdentifier, errorMessages has the texts of the rules that the key does not fit (with the fix), and errorDescription has the field and the first text. The stored credential definition does not change.
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
The field and the problem. With errorType, the field, then the first text of errorMessages.
Possible values: [signing_key_does_not_fit, eaa_category_claim_reserved]
signing_key_does_not_fit: the certificate of the signing key of a configuration does not fit the credential category of the configuration, or the key of an mDL has no ISO/IEC 18013-5 Document Signer profile. eaa_category_claim_reserved: a configuration with the category eaa, qeaa or pub-eaa has a claim at the place of the EAA category of ETSI TS 119 472-1 (the issuer adds the category). Other errors have no errorType.
The field of the error, with the position of the configuration in the request. credentialDefinitions[<index>].cryptographicKeyIdentifier for signing_key_does_not_fit. credentialDefinitions[<index>].claims, or credentialDefinitions[<index>].type for a W3C VC, for eaa_category_claim_reserved.
All the texts of the refusal, one for each rule that does not fit, with the fix (the category rule first, then the mDL rule). Only with errorType. For signing_key_does_not_fit they are the same as signingKeyCheck.messages of the configuration and certificateAssessment.categoryMessages (or mdlConfigurationMessages) of the key.
{
"errorCode": 400,
"errorDescription": "credentialDefinitions[0].cryptographicKeyIdentifier: A QEAA needs a qualified seal certificate. This key has an EAA certificate (no QcCompliance statement, no QcSSCD statement, no QcType eseal). Request a certificate with the preset QEAA provider (qeaa-provider).",
"errorType": "signing_key_does_not_fit",
"errorField": "credentialDefinitions[0].cryptographicKeyIdentifier",
"errorMessages": [
"A QEAA needs a qualified seal certificate. This key has an EAA certificate (no QcCompliance statement, no QcSSCD statement, no QcType eseal). Request a certificate with the preset QEAA provider (qeaa-provider)."
]
}
Unauthorized
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}
Internal server error
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}