Learn how to integrate a claims source into an OID4VCI workflow

1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.

2. Select Claims sources.

3. Click the Create new button.

4. Insert a meaningful name for your Claims source in the Name field.

5. In the URL field, paste the Public Claims Source URL generated when you started the claims source application.

6. In the Authorization type section, select API Key as the type.

7. In the API Key field, paste supersecretapikey. This is the API key used by the sample claims source application to control access. In Production environments, it is strongly recommended to use a more secure API key.

8. Paste the following code into the Request parameters field:

   {
       "email": {
           "mapFrom": "claims.email"
       }
   }

   This maps the user's email claim to a request parameter that will be sent to the claims source to retrieve user-specific information.

   • In Authorization code flows it is provided by the Authentication provider.
   • In Pre-authorized code flows it is provided by the issuer as part of the credential offer.

9. Select Save to create the Claims source.

Make a request of the following structure to configure a new claims source:

POST /v1/claim-sources

{
    "name": "My tutorial Claims source",
    "url": "<CLAIM_SOURCE_URL>", 
    "authorization": { 
        "type": "api-key", 
        "value": "supersecretapikey"
    },
    "requestMethod": "GET",
    "requestParameters": { 
        "email": { 
            "mapFrom": "claims.email"
        } 
    }
}

• url : Replace this with the Public Claims Source URL URL generated when you started the claims source application. The URL should follow this format: https://<YOUR_NGROK_SUBDOMAIN>/claims.
• authorization : Specifies how to access the claims source. The sample claims source application uses an API key (supersecretapikey) for access control. For production environments, it is strongly recommended to use a more secure API key.
• requestParameters : Maps the user's email claim to a request parameter. This parameter is sent to the claims source to retrieve user-specific information.
  • In Authorization code flows it is provided by the Authentication provider.
  • In Pre-authorized code flows it is provided by the issuer as part of the credential offer.

Response

{
    "id": "945214ad-3635-4aff-b51d-61d69a3c8eee"
    // Remaining response properties
}

• id : Unique identifier for the configured Claims source. We will use it in the next step to integrate the Claims source into the OID4VCI workflow.

1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.

2. Select Mobile credential.

3. Select the Create new button.

4. In the Name text box, enter a clear and descriptive title that will appear on the credential in the wallet, for example "Enriched Credential".

5. In the Description text box, enter a clear and descriptive description that will appear on the credential in the wallet, for example "Credential with integrated claims source".

6. In the Credential type text box, enter a unique identifier for the credential type, for example com.example.credentialwithclaims.

7. Paste the following JSON into the Claim mappings text box:

   {
       "com.example.personaldetails.1": {
           "name": {
               "mapFrom": "claims.name",
               "type": "string"
           },
           "email": {
               "mapFrom": "claims.email",
               "type": "string"
           },
           "age": {
               "mapFrom": "claims.age",
               "type": "number"
           }
       }
   }

   The age claim will be retrieved from the Claims source configured in the next step, while the name and email claims will be retrieved from the authentication provider (e.g., Auth0) during the OID4VCI workflow.

8. Use the Claim source dropdown to select the Claims source you created in the previous step. This will allow the credential to retrieve claims from the configured Claims source during issuance.

9. Enter "1" in the Months text box in the Validity for panel to set the credential expiration period.

10. Select the Create button to create the credential configuration.

Make the following request to create a simple mDoc credentials configuration that includes the holder's name and e-mail, but also their age from your configured Claims source:

POST /v2/credentials/mobile/configurations

{
    "type": "com.example.credentialwithclaims",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "com.example.personaldetails.1": {
            "name": {
                "mapFrom": "claims.name",
                "type": "string"
            },
            "email": {
                "mapFrom": "claims.email",
                "type": "string"
            },
            "age": { 
                "mapFrom": "claims.age", 
                "type": "number"
            }
        }
    },
    "branding": {
        "name": "My Credential with Claims",
        "description": "For rich credential issuance experience",
        "backgroundColor": "#a22dd8ff"
    },
    "claimSourceId": "<CLAIM_SOURCE_ID>", 
    "includeStatus": true
}

• age : This claim represents the user's age. It is retrieved from the Claims source and stored in the users claims object as a new age property. During credential issuance claims.age will be mapped to the age claim in the credential.
• claimSourceId : Replace this with the id value returned in the response when you configured the Claims source in the previous step.

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.

This offer can be created either via the MATTR Portal or the MATTR VII Platform APIs.

POST /v1/openid/offers

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

Make the following request to generate a new Pre-authorized Code flow Credential offer:

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

• credentials : Populate the array with the id element returned in the response when you created an mDocs credentials configuration in the previous step.
• email : Replace <YOUR_USER_EMAIL> with the email address you used when you set up your local claims source.

Response

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

You will need to obtain two important elements from the response:

• transactionCode : This is the one-time code that the user will need to provide in order to claim the credential. In production deployments you will need to provide it to the user through a different channel (e.g., email, SMS, printed on paper).
• uri : This URI can be used by a digital wallet to trigger the OID4VCI workflow. Use one of the following tools to convert the uri value to a QR code (make sure you use the Plain text option where available) and save the generated QR code as an image file.
  • https://www.the-qrcode-generator.com/
  • http://goqr.me/api/
  • https://www.qr-code-generator.com/