Skip to main content

Read credential definition

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

Retrieves a credential definition by its ID, with the credential configurations that it holds in credentialDefinitions. Each configuration holds the credential format, the claims and the issuance settings.

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

Responses​

Credential definition retrieved successfully

Response Headers
    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.

    • ]
    Loading...
    Last updated on