Learn how to create a standards-compliant mDoc Credential configuration

Credential type

The credential type is used to differentiate between different types of credentials. It is a unique identifier that specifies the purpose and structure of the credential being issued.

It is set using the type property when creating a credential configuration:

{
    "type": "org.iso.18013.5.1.mDL"
 
    // Rest of the credential configuration
}

Credential content

The credential content defines the specific information that will be included in the credential. This can include various claims about the holder, such as their name, email address, and any other relevant data.

The content is set using the claimMappings object, as shown in the following example:

{
    "claimMappings": {
        "com.example.personaldetails.1": {
            "name": {
                "mapFrom": "claims.name",
                "type": "string",
                "required": true
            },
            "email": {
                "mapFrom": "claims.email",
                "type": "string",
                "defaultValue": "Not provided"
            }
        }
    },
 
    "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60"
 
    // Rest of the credential configuration
}

This example maps claims into a single namespace (com.example.personaldetails.1) and defines two claims within it:

• name : This claim is mapped from the claims.name property in the claim source. It is of type string and is marked as required, meaning that the issuance process will fail if this claim is not provided.
• email : This claim is also mapped from the claims.email property in the claim source. It is of type string but is not marked as required. If the claim is not provided, it will default to the value “Not provided”.

The claimSourceId property specifies the claims source from which claims are dynamically retrieved as part of the issuance flow.

Credential validity

Credential validity defines the period during which the credential is considered valid and can be used for its intended purpose. This is set using a combination of three properties in the credential configuration. Examples include:

Revocation support

MATTR VII allows you to update the status of issued credentials, enabling you to revoke or suspend credentials when necessary. Verifiers can check the status of a presented credential without compromising the holder’s privacy.

Support for credential revocation is configured as part of the credential configuration, using the includeStatus boolean:

{
    "includeStatus": true
 
    // Rest of credential configuration
}

• includeStatus : When set to true, issued credentials are revocable. They’ll include a status object, which refers a Status list where the credential status is indicated.

Credential branding

Credential configurations can include information regarding how to brand them when they are displayed in a digital wallet. This is useful for enhancing the user experience and ensuring that the credential is easily recognizable.

Branding is controlled via the following properties of the branding object:

{
    "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"
    }
 
    // Rest of credential configuration
}

• name : Displayed on the top part of the credential.
• description : Displayed below the name field.
• backgroundColor : Applied as the credential background color.
• watermarkImage : Displayed as a pattern on top of the credential.
• issuerLogo : Displayed on the bottom part of the credential.
• issuerIcon : Displayed next to the issuer’s name.

Putting it all together

Request

Make the following request to create an mDoc credentials configuration:

POST /v2/credentials/mobile/configurations

Request body

{
    "type": "com.example.credentialconfiguration.1",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "com.example.personaldetails.1": {
            "name": {
                "mapFrom": "claims.name",
                "type": "string",
                "required": true
            },
            "email": {
                "mapFrom": "claims.email",
                "type": "string",
                "required": true
            },
            "age": {
                "mapFrom": "claims.age",
                "type": "number"
            }
        }
    },
    "branding": {
        "name": "My Credential Configuration Tutorial Credential",
        "description": "Credential Configuration Best Practices",
        "backgroundColor": "#d82db3ff"
    },
    "claimSourceId": "<CLAIM_SOURCE_ID>",
    "includeStatus": true
}

• claimSourceId : If you completed the Claim source tutorial, you can replace this with the ID of the claim source you created. Otherwise, omit this line from the request body.

Response

{
    "id": "294868aa-3814-4a50-9862-5ff48381a8e5"
    //... rest of your credential configuration
}

• id : Unique identifier for the created mDocs credentials configuration. This ID is used to create a Credential offer in the next step.

Create a Credential offer

You can now generate a Credential offer and share it with the intended holder.

Make sure you create a credential offer that matches the flow you are implementing.