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, trustAnchor, kid, supportRevocation and revocationMethod are immutable after creation, and this operation does not accept them.

Request

Path Parameters

credentialDefinitionId stringrequired

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

Header Parameters

X-SandboxOrgId stringrequired
Optional. Unique identifier of the sandbox organisation to use for this request. When you send this header, the service runs the operation in the context of the named sandbox organisation, that is, against the wallet of that sandbox organisation and not against the main wallet of the organisation. Leave the header out to use the main wallet.
The service reads this header only when you authenticate with a bearer access token. When you authenticate with an API key, the service takes the sandbox organisation from the API key and ignores this header. To run an API-key call in a sandbox organisation, bind the key to the sandbox organisation with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org instead.
X-SubwalletId is the deprecated name of this header. The service continues to accept it, but X-SandboxOrgId wins if you send both headers.
The sandbox organisation must exist, must belong to your organisation and must be deployed. An unknown identifier, an identifier of a sandbox organisation that is not deployed, and an identifier that belongs to a different organisation all make the call fail with HTTP 400.
Example: 6889e1a4c5b2f30001a3d710

application/json

Body

required

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

label string

Possible values: >= 3 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 at least 3 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 to change a configuration that the issuer already published. Omit id to add a new configuration. Leave an existing configuration out of the array to remove it. Do not supply a configuration field such as credentialFormat or claims at the top level, because the issuer rejects the request.

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.

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 color code for the credential card background (e.g. #FFFFFF).

textColor string

Hex color 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

200

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

application/json

Schema

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 number
Number of days until the issued credential expires.
supportRevocation boolean
When true, the issuer supports revocation of credentials from this configuration.
revocationMethod string
Possible values: [status_list, status_list_2021, swiss_token_status_list_v1]
Method used for credential revocation. status_list uses the IETF Token Status List specification. status_list_2021 uses the W3C Status List 2021 specification. swiss_token_status_list_v1 uses the Swiss profile of Token Status List.
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]
Cryptographic key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. cose_key is valid only for the mso_mdoc format.
authorizationRequestType string
Possible values: [authorization_details, scope_based]
How the wallet requests authorization during the OID4VCI issuance flow. authorization_details uses RFC 9396 Rich Authorization Requests. scope_based uses OAuth 2.0 scope values.
scope string
OAuth 2.0 scope value of this credential configuration. The issuer sets this field when authorizationRequestType is scope_based.
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 color code for the credential card background (e.g. #FFFFFF).
textColor string
Hex color 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.
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.
trustAnchor stringrequired
Possible values: [did:key, x509]
DID method or key type used as the trust anchor for credential issuance.
kid stringrequired
Key Identifier (kid) referencing the cryptographic key used to sign issued credentials.
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.
systemManaged booleanrequired
When true, the platform manages this credential definition. You cannot change or delete a system managed credential definition.
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 color code for the credential card background (e.g. #FFFFFF).
textColor stringrequired
Hex color 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 numberrequired
Number of days until the issued credential expires.
supportRevocation booleanrequired
When true, the issuer supports revocation of credentials from this credential definition.
revocationMethod stringrequired
Possible values: [status_list, status_list_2021, swiss_token_status_list_v1]
Method used for credential revocation. status_list uses the IETF Token Status List, status_list_2021 uses the W3C Status List 2021, swiss_token_status_list_v1 uses the Swiss profile.
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]
Cryptographic 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.
]
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.
]

Example (from schema)

{
  "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,
        "supportRevocation": true,
        "revocationMethod": "status_list",
        "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",
        "claims": {
          "claims": [
            {
              "path": [
                "address",
                "country"
              ],
              "mandatory": true,
              "limitDisclosure": true
            }
          ]
        },
        "credentialDefinition": {
          "claims": [
            {
              "path": [
                "credentialSubject",
                "identifier"
              ],
              "mandatory": true
            }
          ]
        }
      }
    ],
    "version": "version_01",
    "trustAnchor": "did:key",
    "kid": "string",
    "enforceWUA": true,
    "supportInteractiveAuthorisationEndpoint": true,
    "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": 30,
    "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
        }
      ]
    },
    "credentialDefinition": {
      "claims": [
        {
          "path": [
            "credentialSubject",
            "identifier"
          ],
          "mandatory": true
        }
      ]
    }
  }
}

400

The request is invalid. The issuer returns this status when no credential definition matches credentialDefinitionId, when the request body is not valid JSON, when label is shorter than 3 characters or uses a reserved platform value, when credentialBindingMethods holds cose_key for a credential format other than mso_mdoc, when a configuration field is present both at the top level and in a credentialDefinitions entry, or when the claims fail validation.

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

401

Unauthorized

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

500

Internal server error

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

Loading...