GuidesOID4VCICredential configuration

How to create a Credential configuration

As part of an OpenID4VCI issuance workflow you must create a Credential configuration. A Credential configuration is a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

The OpenID4VCI issuance workflow currently supports configuration of the following credentials formats:

  • CWT and Semantic CWT credentials
  • JSON credentials
  • mDocs

You can also create credential configurations via the MATTR Self Service Portal.

Create an mDocs credential configuration

Request

Make a request of the following structure to create a new mDocs credential configuration:

HTTP
POST /v2/credentials/mobile/configurations

Request body

JSON
{
  "type": "com.example.employeecredential.1",
  "expiresIn": {
    "months": 1
  },
  "claimMappings": {
    "com.example.personaldetails.1": {
      "first_name": {
        "mapFrom": "claims.given_name",
        "type": "string",
        "required": true
      },
      "last_name": {
        "mapFrom": "claims.last_Name",
        "type": "string",
        "required": true
      },
      "date_of_birth": {
        "mapFrom": "claims.birthDate",
        "type": "string",
        "required": true,
        "defaultValue": "Unknown"
      }
    }
  },
  "branding": {
    "name": "Course credential",
    "description": "Diploma in Management",
    "backgroundColor": "#860012",
    "watermarkImage": "https://example-path-to-image-data.com",
    "issuerLogo": "data:image/png;base64,anything", 
    "issuerIcon": "data:image/svg+xml;base64,anything"
  },
  "claimSourceId": "945214ad-3635-4aff-b51d-61d69a3c8eee",
  "includeStatus": false
}
  • type (required): Used to differentiate between different mDoc credential configurations on your tenant. Thus, its value must:
    • Be unique across all JSON credentials configurations on your tenant.
    • Not be VerifiableCredential.
    • When set to org.iso.18013.5.*.mDL (where * is a positive integer), MATTR VII recognises that this is attempt to create an mDL credential configuration and will fail if the validity period is set to 447 days or more.
  • expiresIn (optional): Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds. When type is set to org.iso.18013.5.*.mDL (where * is a positive integer), MATTR VII recognises that this is an mDL credential configuration and will fail if expiresIn is 447 days or more.
  • claimMappings : This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more of the following attributes:
    • mapFrom : References the path in the user object where the claim is available.
      • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']”).
      • mapFrom is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
    • type : Claim data type. type is optional when defaultValue is provided. The following data types are supported:
      • boolean
      • number
      • string
      • binary: Mapped value must be in base64 string format.
      • date : Mapped value must be in YYYY-MM-DD format.
      • dateTime : Mapped value must be in YYYY-MM-DD HH:MM:SS format (ISO 8601 compliant).
      • array
      • object
      • org.iso.18013.5.1.driving_privileges : This type is unique for mDL credentials and details the holder’s driving privileges. Mapped value must be a compliant org.iso.18013.5.1.driving_privileges array, as per ISO/IEC 18013-5. The array can include the following optional items:
        • issue_date: When provided, must be in YYYY-MM-DD format.
        • expiry_date: When provided, must be in YYYY-MM-DD format.
        • vehicle_category_code (required): Must be a vehicle category code as per ISO/IEC 18013-1.
        • codes: When provided, must be an array of code information, and can include the following optional fields:
          • code (required): Must be a code as per ISO/IEC 18013-2 Annex A.
          • sign: When provided, must be a sign as per ISO/IEC 18013-2 Annex A.
          • value: When provided, must be a value as per ISO/IEC 18013-2 Annex A.
    • required : Indicates whether the claim is required. When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail. Defaults to false.
    • defaultValue : Used to populate the claim with a static value when mapping is unsuccessful. When defaultValue is provided, mapFrom is optional.
  • branding (optional): Used to apply branding to issued credentials:
    • name : Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder’s digital wallet (see image below).
    • description : Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder’s digital wallet (see image below).
    • backgroundColor : Insert a colour hex code to use for the credential background color in the holder’s digital wallet (see image below).
    • watermarkImage : Watermarks are displayed as a pattern on the credential in the holder’s digital wallet (see image below). You can provide either a URL to the image, or a Data URI (base64 encoded) with the following requirements:
      • URL/URI must be publicly available.
      • File must be 245x150px in size.
      • svg and png files are supported. We recommend using svg files to allow proper scaling across the UI and enable optimal performance.
      • If no watermark image is provided, a wave pattern is applied to the credentials by default.
      • The recommended maximum size of watermarkImage is 150kb.
    • issuerLogo : The issuer logo is displayed on the bottom part of the credential in the holder’s digital wallet (see image below). When not provided, the issuer’s name and issuerIcon are used instead. You can provide either a URL to the image, or a Data URI (base64 encoded) with the following requirements:
      • URL/URI must be publicly available.
      • File must be 140x42px in size.
      • svg and png files are supported. We recommend using svg files to allow proper scaling across the UI and enable optimal performance.
      • Transparencies are allowed for svg or png images.
      • The recommended maximum size of issuerLogo is 50kb.
    • issuerIcon : The issuer icon is displayed next to the issuer’s name when the credential is offered to the holder. It is also displayed next to the issuer’s name on the bottom part of the credential when issuerLogo is not provided. When issuerIcon is not provided, the first letter from the issuer name is used instead. You can provide either a URL to the image, or a Data URI (base64 encoded) with the following requirements:
      • URL/URI must be publicly available.
      • File must be 32x32px in size.
      • svg and png files are supported. We recommend using svg files to allow proper scaling across the UI and enable optimal performance.
      • Transparencies are allowed for svg or png images.
      • The recommended maximum size of issuerIcon is 15kb.
      • If issuerIcon is not provided, the first letter of the issuer name is displayed instead.
  • claimSourceId (optional): References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.
  • includeStatus : When set to true, issued mDocs are revocable. They include a status object, which refers a Status list where the mDoc’s status can be changed to valid, invalid, or suspended.

Refer to mDocs signing certificate selection to learn more about how MATTR VII automatically select suitable IACA and DSC certificates when signing mDocs.

Response

JSON
{
    "id": "294868aa-3814-4a50-9862-5ff48381a8e5",
    "type": "com.example.employeecredential.1"
    //... rest of your credential configuration
}
  • id : Uniquely identifies the created Credential configuration. This identifier can be used to include this Credential configuration in a Credential offer, or to retrieve, update or delete the Credential configuration.

Once the Credential configuration is created, its details are publicly available on https:// {your_tenant_url}/.well-known/openid-credential-issuer. This enables relying parties to verify credentials issued using this Credential configuration.

Branded mDoc

Credential branding explainer
Claims sourceCredential revocation