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. It tells the wallet that the following fields first_name, last_name and id_number will be included in the verifiable credential:

Credential configuration Example:

credential-configuration.json

{
  "format": "jwt_vc_json-ld", // (1)!
  "credential_definition": { // (2)!
    "@context": ["https://www.w3.org/ns/credentials/v2"], // (3)!
    "type": ["VerifiableCredential", "IdCard"] // (4)!
  },
  "credential_metadata": {
    "display": [ // (5)!
      {
        "name": "ID Card", // (6)!
        "locale": "en-US", // (7)!
        "logo": { // (8)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", // (9)!
          "alt_text": "Example ID card logo" // (10)!
        },
        "description": "This is an example of an ID card", // (11)!
        "background_color": "#FFFFFF", // (12)!
        "text_color": "#000000", // (13)!
        "background_image": { // (14)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
        }
      }
    ],
    "claims": [ // (15)!
      {
        "path": [ // (16)!
          "credentialSubject",
          "first_name"
        ],
        "mandatory": false, // (17)!
        "display": [ // (18)!
          {
            "name": "First Name", // (19)!
            "locale": "en-US" // (20)!
          }
        ]
      },
      {
        "path": [
          "credentialSubject",
          "last_name"
        ],
        "mandatory": false,
        "display": [
          {
            "name": "Last Name",
            "locale": "en-US"
          }
        ]
      },
      {
        "path": [
          "credentialSubject",
          "id_number"
        ],
        "mandatory": false,
        "display": [
          {
            "name": "ID Number",
            "locale": "en-US"
          }
        ]
      }
    ]
  }
}

Required: the format of the issued verifiable credential.
Required: this object defines the layout of the credential.
Required: array of JSON-LD context URLs and objects.
Required: array designating the types the credential supports.
Optional: defines how the wallet should display the credential.
Required: display name of the credential.
Optional: locale for the display object, in IETF BCP 47 format (e.g. en-US).
Optional: information about the logo of the credential.
Required: a URI where the wallet can obtain the image, using either the https:// or the data: scheme.
Optional: alternative text for the logo.
Optional: description of the credential.
Optional: hexadecimal representation of the background colour.
Optional: hexadecimal representation of the text colour.
Optional: information about the background image of the credential. Takes the same uri and alt_text fields as logo.
Required: array of claim objects describing the claims included in the credential. The two claims below first_name follow the same structure.
Required: array of strings describing the path to the claim. The path must start with credentialSubject, as this is the standard location for claims in a jwt_vc_json-ld credential.
Optional: whether the claim is mandatory for the credential. Defaults to false.
Optional: how the claim should be displayed in the wallet.
Optional: display name of the claim.
Optional: locale for the claim display object, in IETF BCP 47 format (e.g. en-US).

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. When updating the path array, the first entry must be "credentialSubject" as that is the default location for claims in a jwt_vc_json-ld credential.

Once you have decided what information to include you can specify the credential type, you do this by replacing IdCard with your own value.

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.

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