Create a Credential configuration

Introduction

In an OpenID4VCI issuance workflow, Credential offers are created based on Credential configurations. These are templates that define rules and parameters that control the structure and content of the credentials being issued.

The purpose of this tutorial is to demonstrate how to create a Credential configuration using the MATTR Portal or via API calls.

Prerequisites

• Ensure you have completed either the Authorization Code or Pre-authorized Code tutorials, as the claims source tutorial builds upon them.
• Review the Credential configuration overview page for a detailed explanation of the key concepts and considerations involved in creating a credential configuration.

Guide overview

When planning any credential configuration, an issuer should take the following factors into account:

• Credential type: Used to uniquely identify credentials issued via this configuration.
• Credential content: Decide what information will be included in the credential, and how it will be structured.
• Credential validity: Set the appropriate validity period to reflect how long the credential should be considered accurate and trustworthy.
• Revocation support: Determine whether the credential needs to support revocation status updates.
• Branding configuration: Specify how the credential should appear in a digital wallet. While display conventions are not yet standardized, this tutorial uses MATTR’s proprietary format to support branding, clarity, and holder trust.

This tutorial will walk you through each of these steps and explain the different considerations, options, and best practices to help you create a well-formed credential configuration.

{
    "type": "org.iso.18013.5.1.mDL"

    // Rest of the credential configuration
}

{
    "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
}

{
    "expiresIn": {
        "days": 30
    }

    // Rest of the credential configuration
}

{
    "validFrom": {
        "defaultValue": "2023-01-01T00:00:00Z"
    },
    "validUntil": {
        "defaultValue": "2023-02-01T23:59:59Z"
    }

    // Rest of the credential configuration
}

{
    "includeStatus": true

    // Rest of credential configuration
}

{
    "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
}

POST /v2/credentials/mobile/configurations

{
    "type": "com.example.credentialconfiguration.2",
    "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
}

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

POST /v1/openid/offers

{
    "credentials": ["<CREDENTIAL_CONFIGURATION_ID>"]
}

POST /v1/openid/offers/pre-authorized

{
    "credentials": ["707e920a-f342-443b-ae24-6946b7b5033e"], 
    "transactionCodeConfiguration": {
        "inputMode": "numeric",
        "description": "Please enter the one-time code that was sent to you via email."
    },
    "claims": {
        "name": "John Doe", 
        "email": "<YOUR_USER_EMAIL>"
    },
    "expiresIn": {
        "minutes": 10
    }
}

{
    "id": "e6e5e43c-8053-464a-aca4-ca43da765c97",
    "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Flearn.vii.au01.mattr.global%22%2C%22credentials%22%3A%5B%22b7b380be-1467-446b-8683-1d131e6532be%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%229K3N9UPQD-Hs5f5-gPx0fRJEmb1XTZsWszzXL024pV0%22%2C%22tx_code%22%3A%7B%22length%22%3A6%2C%22input_mode%22%3A%22numeric%22%2C%22description%22%3A%22Please%20enter%20the%20one-time%20code%20that%20was%20sent%20to%20you%20via%20email.%22%7D%7D%7D%7D",  
    "userId": "6e30dd69-c867-4279-afd3-e6619253b4a4",
    "expiresAt": "2025-08-25T01:39:00.523Z",
    "transactionCode": "763677"
}

Test the workflow

1. Open the GO hold example app.
2. Select Scan.
3. Scan the QR code generated in the previous step.
4. Review the credential offer and select Accept.
5. Follow the issuance workflow instructions to claim the credential.
   • If you are testing an Authorization Code flow, you will be redirected to the configured authentication provider to authenticate. After a successful authentication you will be redirected back to the GO hold app to continue the issuance workflow.
   • If you are testing a Pre-authorized Code flow, you will also be prompted to enter the transactionCode value returned in the response when you created the credential offer.

You should now have a new credential your MATTR GO Hold app.

What's next?

Check out more resources on MATTR Learn that will enable you to:

• Configure a Claims source to retrieve data from compatible data sources and use it in the issued credential.
• Configure an Interaction hook to redirect the user to custom components as part of the issuance workflow.