Learn how to configure an OID4VCI Pre-authorized Code flow to issue an mDoc into a digital wallet

1. Log into the MATTR Portal.
2. In the navigation panel on the left-hand side, expand the Platform Management menu.
3. Select Certificates.
4. Select the Create new button.
5. Use the Type radio button to select IACA - Issuing Authority Certificate Authority.
6. Use the Management method radio button to select MATTR managed.
7. Use the Country dropdown list to select an issuing country.
8. Select the Create button to create the IACA certificate.
   The IACA is created as inactive by default.
9. Use the Status radio button to select Active.
10. Select the Update button to activate the IACA certificate.

Step 1: Obtain a MATTR VII access token

All of the MATTR VII endpoints you will use in this tutorial are protected, so you will first need to use your tenant details to make a request of the following structure and obtain an access token:

POST https://{auth_server}/oauth/token

• auth_server : Replace with the auth_url value from your tenant details.

{
  "client_id": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
  "client_secret": "Wzc8J**********************************************************",
  "audience": "learn.vii.au01.mattr.global",
  "grant_type": "client_credentials"
}

• Replace client_id, client_secret and audience with your own tenant details.
• Keep grant_type as client_credentials.

Response

{
  "access_token": "eyJhb********************************************************************",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Use the returned access_token value as a bearer token for all requests to your MATTR VII tenant in the next steps of this tutorial.

Step 2: Create the IACA certificate

1. Make the following request to your MATTR VII tenant to create an IACA:

POST /v2/credentials/mobile/iacas

The response will include an id element which you will use in the next step.

2. Make the following request to activate the IACA you just created:

PUT /v2/credentials/mobile/iacas/{iacaId}

• iacaId: Replace with the id element returned in the response when you created the IACA in the previous steps.

{
    "active": true
}

Your IACA is now active and can be used to sign mDocs.

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 "My First Pre-Auth Credential".

5. In the Description text box, enter a clear and descriptive description that will appear on the credential in the wallet, for example "For High Assurance Interactions".

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

7. Copy and 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"
       }
     }
   }

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

9. 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:

POST /v2/credentials/mobile/configurations

{
  "type": "com.example.myfirstpreauthcredential",
  "expiresIn": {
    "months": 1
  },
  "claimMappings": {
    "com.example.personaldetails.1": {
      "name": {
        "mapFrom": "claims.name",
        "type": "string"
      },
      "email": {
        "mapFrom": "claims.email",
        "type": "string"
      }
    }
  },
  "branding": {
    "name": "My First Pre-Auth Credential",
    "description": "For High Assurance Interactions",
    "backgroundColor": "#a2d82dff"
  },
  "includeStatus": true
}

The response will include an id element. You will use it to create a Credential offer in the next step.

1. In the navigation panel on the left-hand side, expand the Credential Issuance menu.
2. Select Credential offer.
3. Use the Workflow radio button to select Pre-authorized code flow.
4. Select the Select button.
5. Check the checkbox next to the credential configuration you created in the previous step.
6. Select the Apply button.
7. Select the Generate button.
8. Copy the Transaction code that is displayed on the screen.
   In production deployments you will need to provide it to the user through a different channel (e.g., email, SMS).
9. Download the displayed QR code.
   This QR code will be used by the holder to claim the credential.

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": "john.doe@example.com"
  },
  "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.

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/