Skip to content

Creating Credentials Configurations

This article explains what credential configurations are and how to configure them within the credential issuance service to issue credentials to a wallet.

What is a Credential Configuration?

A credential configuration is a structured representation of the data that the wallet receives from the issuer during the issuance protocol. The credential issuance service uses these definitions to inform the wallet of the content of credentials. You can have multiple credential configurations within your credential issuance service, depending on your own use cases and needs.

The following is a complete example of a credential configuration for an SD-JWT VC. It tells the wallet that the fields first_name, last_name, id_number and the city of an address will be included in the verifiable credential:

Credential configuration Example:
credential-configuration.json
{
  "format": "dc+sd-jwt", // (1)!
  "vct": "urn:example:id-card:1", // (2)!
  "cryptographic_binding_methods_supported": ["jwk"], // (3)!
  "credential_signing_alg_values_supported": ["ES256"], // (4)!
  "proof_types_supported": { // (5)!
    "jwt": {
      "proof_signing_alg_values_supported": ["ES256"]
    }
  },
  "credential_metadata": {
    "display": [ // (6)!
      {
        "name": "ID Card", // (7)!
        "locale": "en-US", // (8)!
        "logo": { // (9)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", // (10)!
          "alt_text": "Example ID card logo" // (11)!
        },
        "description": "This is an example of an ID card", // (12)!
        "background_color": "#FFFFFF", // (13)!
        "text_color": "#000000", // (14)!
        "background_image": { // (15)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
        }
      }
    ],
    "claims": [ // (16)!
      {
        "path": [ // (17)!
          "first_name"
        ],
        "mandatory": false, // (18)!
        "display": [ // (19)!
          {
            "name": "First Name", // (20)!
            "locale": "en-US" // (21)!
          }
        ]
      },
      {
        "path": [
          "last_name"
        ],
        "mandatory": false,
        "display": [
          {
            "name": "Last Name",
            "locale": "en-US"
          }
        ]
      },
      {
        "path": [
          "id_number"
        ],
        "mandatory": false,
        "display": [
          {
            "name": "ID Number",
            "locale": "en-US"
          }
        ]
      },
      {
        "path": [ // (22)!
          "address",
          "city"
        ],
        "mandatory": false,
        "display": [
          {
            "name": "City",
            "locale": "en-US"
          }
        ]
      }
    ]
  }
}
  1. Required: the format of the issued verifiable credential, dc+sd-jwt for an SD-JWT VC.
  2. Required: the type of the credential, which a verifier asks for by this value. It is matched exactly, so choose a value you control and put a version in it. The service does not check for it when you create the configuration, so a missing vct shows only when a wallet requests the credential.
  3. Optional: binds the issued credential to a key the wallet proves it holds, which the credential then carries as cnf.jwk. Present if and only if proof_types_supported is; leave both out to issue a credential that is bound to no key.
  4. Optional: the algorithm the issuer signs the credential with. ES256 is the only one supported.
  5. Optional: the proofs a wallet can send to show it holds its key. jwt with ES256 is the only one supported.
  6. Optional: defines how the wallet should display the credential.
  7. Required: display name of the credential.
  8. Optional: locale for the display object, in IETF BCP 47 format (e.g. en-US).
  9. Optional: information about the logo of the credential.
  10. Required: a URI where the wallet can obtain the image, using either the https:// or the data: scheme.
  11. Optional: alternative text for the logo.
  12. Optional: description of the credential.
  13. Optional: hexadecimal representation of the background colour.
  14. Optional: hexadecimal representation of the text colour.
  15. Optional: information about the background image of the credential. Takes the same uri and alt_text fields as logo.
  16. Required: array of claim objects describing the claims included in the credential. The claims below first_name follow the same structure. Every claim is selectively disclosable.
  17. Required: array of strings describing the path to the claim. The path starts at the top level of the credential.
  18. Optional: whether the claim is mandatory for the credential. Defaults to false.
  19. Optional: how the claim should be displayed in the wallet.
  20. Optional: display name of the claim.
  21. Optional: locale for the claim display object, in IETF BCP 47 format (e.g. en-US).
  22. A nested path. The issued credential carries address as an object with city inside it, and each of the two can be disclosed on its own.

Creating a Credential Configuration

The overall structure of your own credential configuration must be valid. Therefore, we recommend using the example above as a guideline and starting point.

First, keep the format field unchanged. Then, decide what information the verifiable credential should contain and update the claims array accordingly. These values are included in the credential received by holders and verifiers and should therefore be meaningful for the credential. Each path starts at the top level of the credential, and a nested claim is a longer path, such as ["address", "city"].

Names the service writes itself

A claim path must not start with iss, sub, iat, nbf, exp, vct, cnf or status. The service reserves those names for the registered claims of the credential.

Once you have decided what information to include, specify the credential type by replacing urn:example:id-card:1 in vct with your own value. A verifier asks for the credential by this value, in the meta.vct_values of its verification query.

Finally, you can choose to configure the optional display information of your credential, or remove parts of or the entire section. This provides a way to customize the design of the credential. Thus, choose a fitting name and style for the card such that the user can easily recognize the card among their digital credentials. If you choose to use the https:// scheme for the uri fields in background_image and logo, ensure the resources are publicly accessible, as the wallet may fetch the image to show the holder.

W3C verifiable credentials

The service also issues the jwt_vc_json-ld format, a W3C verifiable credential secured as an SD-JWT. Its configuration names the type with a credential_definition of @context and type instead of vct, and every claim path starts with credentialSubject. Examples of a configuration and a credential dataset in this format are in the OpenAPI specification at {credential_issuance_service_URL}/openapi, under POST /credential-configuration/create and POST /issuance/oid4vci/new-session.

Set up the credential issuance service with your Credential Configuration

To set up the credential issuance service with your newly created credential configuration, call the {credential_issuance_service_URL}/credential-configuration/create endpoint on the credential issuance service.

This can be done through the OpenAPI UI accessible on https://{credential_issuance_service_URL}/openapi. From here you can interact with the endpoint by clicking on the "Try it out" button, and adding your own credential configuration in the request body before hitting execute.

Another option is to use curl. Save the configuration above as credential-configuration.json and post it:

curl -X POST \
  '{credential_issuance_service_URL}/credential-configuration/create' \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d @credential-configuration.json

Response

The credential issuance service returns a 201 - created response with the ID of the newly created credential configuration. This confirms successful setup, and the system is now ready to issue credentials to wallets that adhere to the specified configuration.

Header:

{
    "Content-type": "text/plain"
}

Body:

5016c96c-0194-4200-9f57-13d4c8fbb06a