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 the following fields given_name and address.street_name 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", "Passport"], // (4)!
  },
  "credential_metadata": {
    "display": [ // (5)!
      {
        "name": "Passport", // (6)!
        "locale": "en-US", // (18)!
        "logo": { // (7)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", // (8)!
          "alt_text": "string" // (9)!
        },
        "description": "This is a Passport", // (10)!
        "background_color": "#FFFFFF", // (11)!
        "text_color": "#000000", // (11)!
        "background_image": { // (12)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" // (8)!
        }
      }
    ],
    "claims": [ // (13)!
      {
        "path": [ // (14)!
          "credentialSubject",
          "given_name"
        ],
        "mandatory": false, // (15)!
        "display": [ // (16)!
          {
            "name": "Given Name", // (17)!
            "locale": "en-US" // (18)!
          }
        ]
      },
      {
        "path": [ // (14)!
          "credentialSubject",
          "address",
          "street_name"
        ],
        "mandatory": false, // (15)!
        "display": [ // (16)!
          {
            "name": "Street Name", // (17)!
            "locale": "en-US" // (18)!
          }
        ]
      }
    ]
  }
}
  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. Optional: This object defines how the wallet should display the credential
  6. Required: Display name of the credential
  7. Optional: Object with information about the logo of the credential
  8. Required: An URI where the wallet can obtain the image, this can either use the https:// or data: scheme
  9. Optional: Alternative text for the logo
  10. Optional: Description of the credential
  11. Optional: Hexadecimal representation of a color
  12. Optional: Object with information about the background of the credential
  13. Required: Array of claim objects, which describe the claims included in the credential
  14. Required: Array of strings describing the path to the claim. The path must include and start with "credentialSubject", as this is the standard location for claims in a jwt_vc_json-ld credential.
  15. Optional: Boolean indicating whether the claim is mandatory or optional for the credential. Defaults to false if not included.
  16. Optional: Object with information about how the claim should be displayed in the wallet.
  17. Optional: Display name of the claim
  18. Optional: Locale for the 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 Passport 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", // (1)!
  "credential_definition": { // (2)!
    "@context": ["https://www.w3.org/ns/credentials/v2"], // (3)!
    "type": ["VerifiableCredential", "Passport"], // (4)!
  },
  "credential_metadata": {
    "display": [ // (5)!
      {
        "name": "Passport", // (6)!
        "locale": "en-US", // (18)!
        "logo": { // (7)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", // (8)!
          "alt_text": "string" // (9)!
        },
        "description": "This is a Passport", // (10)!
        "background_color": "#FFFFFF", // (11)!
        "text_color": "#000000", // (11)!
        "background_image": { // (12)!
          "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" // (8)!
        }
      }
    ],
    "claims": [ // (13)!
      {
        "path": [ // (14)!
          "credentialSubject",
          "given_name"
        ],
        "mandatory": false, // (15)!
        "display": [ // (16)!
          {
            "name": "Given Name", // (17)!
            "locale": "en-US" // (18)!
          }
        ]
      },
      {
        "path": [ // (14)!
          "credentialSubject",
          "address",
          "street_name"
        ],
        "mandatory": false, // (15)!
        "display": [ // (16)!
          {
            "name": "Street Name", // (17)!
            "locale": "en-US" // (18)!
          }
        ]
      }
    ]
  }
}'

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