Learn

Create a Mobile Credential configuration

You can also create a Mobile Credential configuration via our Self service portal.

Request

Make a request of the following structure to create a new Mobile Credential configuration:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/v2/credentials/mobile/configurations
json
Copy to clipboard.
1{
2  "type": "com.example.employeecredential.1",
3  "expiresIn": {
4    "months": 1
5  },
6  "claimMappings": {
7    "com.example.personaldetails.1": {
8      "first_name": {
9        "mapFrom": "claims.given_name",
10        "type": "string",
11        "required": true
12      },
13      "last_name": {
14        "mapFrom": "claims.last_Name",
15        "type": "string",
16        "required": true
17      },
18      "date_of_birth": {
19        "mapFrom": "claims.birthDate",
20        "type": "string",
21        "required": true
22      }
23    }
24  },
25  "branding": {
26    "name": "Course credential",
27    "description": "Diploma in Management",
28    "backgroundColor": "#860012",
29    "watermarkImage": "https://example-path-to-image-data.com",
30    "issuerLogo": "data:image/png;base64,anything", 
31    "issuerIcon": "data:image/svg+xml;base64,anything"
32  },
33  "claimSourceId": "945214ad-3635-4aff-b51d-61d69a3c8eee"
34}

  • type (required): Used to differentiate between different Mobile credential configurations on your tenant. Thus, its value must:

    • Be unique across all Mobile credential configurations on your tenant.

    • Not be VerifiableCredential.

  • expiresIn (required): Used to determine when will issued credentials expire. Can include any combination of years, months and days. Note that credential issuance will fail if the credential expiry date is later than that of the Document Signer Certificate (DSC) used to sign it. Refer to Create a DSC for more information.

  • claimMappings (required): 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: Path to the mapped claim in the configured claims source:

      • 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

      • date: In YYYY-MM-DD format.

      • dateTime: 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 detail the holder's driving privileges:

        • issue_date: In YYYY-MM-DD format.

        • expiry_date: In YYYY-MM-DD format.

        • vehicle_category_code

    • required (optional): Indicates whether the claim is required (default: false). When a required claim is not available, credential issuance will fail.

    • defaultValue (optional): Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom and type are optional.

      Refer to Credential configuration claims to learn more about how this object is created and handled.

  • 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 included 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 245x150 px 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 150 KB.

    • 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 140x42 px 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.

      • Recommended maximum size for issuerLogo is 50 KB.

      • If no logo is provided, the first letter of the issuer name is displayed instead.

    • 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 32x32 px 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.

      • Recommended maximum size for issuerIcon is 15 KB.

  • claimSourceId (optional): References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

Response

json
Copy to clipboard.
1{
2    "id": "294868aa-3814-4a50-9862-5ff48381a8e5",
3    "type": "com.example.employeecredential.1",
4//... rest of your credential configuration
5}

  • id: Uniquely identifies the created credential configuration. This identifier can be used to create an offer based on this credential configuration, or to retrieve, update or remove the credential configuration.

Branded credential

The following image depicts how the credential created above would look like once available in the holder's digital wallet. It might help you better understand how to brand your own credential:

https://www.datocms-assets.com/38428/1704936881-branding.png?auto=format

What's next?

Now that you have created a credential configuration, you can proceed to create a credential offer based on this configuration.