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. It tells the wallet that a studentId, dateOfBirth and enrollmentYear will be included in the verifiable credential:

Credential configuration Example:
{
    "format": "jwt_vc_json-ld", // (1)!
    "credential_definition": { // (2)!
        "@context": ["https://www.w3.org/ns/credentials/v2"], // (3)!
        "type": ["VerifiableCredential", "StudyID"], // (4)!
        "credentialSubject": { // (5)!
            "studentId": {},
            "dateOfBirth": {},
            "enrollmentYear": {}
        }
    },
    "display": { // (6)!
        "name": "Passport", // (7)!
        "logo": { // (8)!
            "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", // (9)!
            "alt_text": "Credential logo" // (10)!
        },
        "description": "This is a Passport", // (11)!
        "background_color": "#FFFFFF", // (12)!
        "text_color": "#000000", // (12)!
        "background_image": { // (13)!
            "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" // (9)!
        }
    }
}
  1. Required: This describes the format of the issued verifiable credential.
  2. Required: This object defines the layout of the credential.
  3. Required: Array of JSON-LD context URLs and objects.
  4. Required: Array designating the types the certain credential supports.
  5. Required: Object that defines which claims that goes into the credential.
  6. Optional: This object defines how the wallet should display the credential
  7. Required: Display name of the credential
  8. Optional: Object with information about the logo of the credential
  9. Required: An URI where the wallet can obtain the image, this can either use the https:// or data: scheme
  10. Optional: Alternative text for the logo
  11. Optional: Description of the credential
  12. Optional: Hexadecimal representation of a color
  13. Optional: Object with information about the background of the credential

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 credentialSubject accordingly. These values are included in the credential received by holders and verifiers and should therefore be meaningful for the credential.

Once you have decided what information to include you can specify the credential type, you do this by replacing StudyID 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:

curl -X 'POST' \
  '{credential_issuance_service_URL}/credential-configuration/create' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "format": "jwt_vc_json-ld",
  "credential_definition": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2"
    ],
    "type": [
      "VerifiableCredential",
      "StudyID"
    ],
    "credentialSubject": {
      "studentId": {},
      "dateOfBirth": {},
      "enrollmentYear": {}
    }
  },
  "display": {
    "name": "Passport",
    "logo": {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
      "alt_text": "Credential logo"
    },
    "description": "This is a Passport",
    "background_color": "#FFFFFF",
    "text_color": "#000000",
    "background_image": {
      "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
    }
  }
}'

Response

The credential verification 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:

0298bb24b25ad8162de3af2dc30971de43bd002000