Create credential definition

POST 
/v2/config/digital-wallet/openid/sdjwt/credential-definition

Creates a new credential definition for OpenID for Verifiable Credential Issuance (OID4VCI) 1.0. Each entry of the credentialDefinitions array holds one credential configuration, with its credential format, claims and issuance settings. The issuer publishes every entry in the OID4VCI Credential Issuer Metadata and uses it as the template for the credentials it issues. Upload the card artwork with the update logo image and update cover image operations after this operation returns.

Request

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

Credential definition to create. Supply label with at least 3 characters, and one credentialDefinitions entry for each credential configuration.

label stringrequired

Possible values: >= 3 characters

Human-readable label describing the intended use of this credential definition (e.g. 'Issue Portable Document A1'). Used to identify the credential definition in the issuer's dashboard. The value must contain at least 3 characters. 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. Supply one entry for each credential configuration that the issuer must publish. Do not repeat version, trustAnchor, kid or enforceWUA in an entry, and do not supply a configuration field such as credentialFormat or claims at the top level, because the issuer rejects the request.
Array [
label string
Human-readable label describing the intended use of this credential configuration.
expirationInDays number
Number of days until the issued credential expires. Defaults to 30. The issuer calculates the expiry date from the issuance time.
supportRevocation boolean
When true, enables credential revocation support. Defaults to false.
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 and is valid only when credentialFormat is jwt_vc_json. swiss_token_status_list_v1 uses the Swiss profile of Token Status List. Defaults to status_list.
enforceCredentialUniqueness boolean
When true, ensures each credential under this configuration is unique per holder. Defaults to false.
supportCredentialReissuance boolean
When true, allows holders to request reissuance of expired or near-expiry credentials. Defaults to false.
credentialBindingMethods string[]
Possible values: [did:key, jwk, cose_key]
Cryptographic key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. You can use cose_key only when credentialFormat is mso_mdoc.
authorizationRequestType string
Possible values: [authorization_details, scope_based]
Determines how the wallet requests authorization during the OID4VCI issuance flow. authorization_details uses RFC 9396 Rich Authorization Requests and forbids scope. scope_based uses OAuth 2.0 scope values and requires scope. Defaults to authorization_details.
scope string
OAuth 2.0 scope value for this credential configuration. Supply this field only when authorizationRequestType is scope_based. Read the available values with the list scope operation.
display object
Display properties for the credential card in wallet UIs. The issuer adds the organisation logo and cover image when you do not supply logo.uri and backgroundImage.uri.
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.
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 stringrequired
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. The format determines which of type, vct and doctype you must supply.
validationPath string
Possible values: [$.vc, $]
JSONPath expression that selects the part of the credential payload that the issuer validates against the claims. Use $.vc when credentialFormat is jwt_vc_json, and $ when credentialFormat is dc+sd-jwt or mso_mdoc.
type string[]
Credential type strings. Required when credentialFormat is jwt_vc_json, and forbidden for the other formats. These values appear in the type field of the issued W3C VC (JWT). You cannot use WalletUnitAttestation here.
vct string
Verifiable Credential Type identifier. Required when credentialFormat is dc+sd-jwt, and forbidden for the other formats (e.g. urn:eu.europa.ec.eudi:pid:1).
doctype string
Document type identifier. Required when credentialFormat is mso_mdoc, and forbidden for the other formats (e.g. org.iso.18013.5.1.lpid).
credentialDefinitionUri string
URL of an external claims schema. The issuer downloads the claims from this URL. Supply this field instead of claims or credentialDefinition. Use the preview operation to check the document before you use the URL.
claims object
Claims of the credential, as claim path pointers. Supply this field when credentialFormat is dc+sd-jwt or mso_mdoc and you do not supply credentialDefinitionUri. Do not supply this field when credentialFormat is jwt_vc_json; use credentialDefinition instead.
claims object[]required
One claim path pointer for each claim that the issuer publishes.
Array [
path undefined[]required
Possible values: >= 1
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. When credentialFormat is mso_mdoc, the first element is the mDoc namespace, the path holds at least two elements, and every path in the configuration uses the same first element.
mandatory boolean
When true, the issuer always includes the claim. The issuer reads a missing field as true.
limitDisclosure boolean
When true, the holder can disclose the claim selectively.
]
credentialDefinition object
Claims of the credential, as claim path pointers. Supply this field when credentialFormat is jwt_vc_json and you do not supply credentialDefinitionUri. Each path starts with credentialSubject, because the issuer validates the claims below $.vc.
claims object[]required
One claim path pointer for each claim that the issuer publishes.
Array [
path undefined[]required
Possible values: >= 1
Claim path pointer that selects the claim below $.vc. Each element is a string for an object key, an integer for an array index, or null for every element of an array. The first element is credentialSubject.
mandatory boolean
When true, the issuer always includes the claim. The issuer reads a missing field as true.
]
]
version string

Possible values: [version_01]

Version of the OpenID for Verifiable Credential Issuance (OID4VCI) specification that the issuer uses for the issuance flow. Set version_01 for OpenID4VCI 1.0. Always supply this field, because the issuer uses an earlier version of the specification when you omit it. You cannot change the value after you create the credential definition.

trustAnchor string

Possible values: [did:key, x509]

Decentralized Identifier (DID) method or key type used as the trust anchor for credential issuance. Determines how the issuer's public key is published and resolved by holders and verifiers. Defaults to did:key. You cannot change the value after you create the credential definition.

kid string

Key Identifier (kid) referencing the cryptographic key used to sign issued credentials. Must match a key configured in the Key Management section. When you send an empty value, the issuer uses the default key of the organisation. You cannot change the value after you create the credential definition.

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. Defaults to false.

supportInteractiveAuthorisationEndpoint boolean

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

display object

Default display properties for every credential configuration of this credential definition. The issuer copies the organisation logo into logo.uri and the organisation cover image into backgroundImage.uri when you leave them empty. To upload your own artwork, use the update logo image and update cover image operations after you create the credential definition.

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.

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.

Responses

200

The issuer created the credential definition and published it in the OID4VCI Credential Issuer Metadata. This operation returns 200, not 201.

Response Headers

application/json

Schema

Schema

credentialDefinition object
The credential definition that the issuer created.
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 label is missing or shorter than 3 characters, when label uses a reserved platform value, when credentialBindingMethods holds cose_key for a credential format other than mso_mdoc, when a credentialDefinitions entry repeats version, trustAnchor, kid or enforceWUA, when a configuration field is present both at the top level and in an entry, when the entries do not agree on authorizationRequestType or scope, when a required field of the credential format is missing, 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...