Learn how to set up a VICAL

Perform the following steps to create an Ecosystem:

1. Log in to the MATTR Portal.
2. Navigate to the Ecosystem page under the Digital Trust Service section.
3. Enter a name for your Ecosystem, such as "My Digital Trust Service".
4. Select the Create button.

Make a request of the following structure to create an ecosystem:

POST /v1/ecosystems

{
  "name": "My Digital Trust Service"
}

• name : This required parameter is the name used to identify your ecosystem.

The response will include an id property, which is the unique identifier for the ecosystem. You will use this ecosystemId in subsequent requests to reference this ecosystem.

Perform the following steps to create a participant:

1. Select the Participants page under the Digital Trust Service section (this page is only visible if you have an existing ecosystem. If you don't have an ecosystem, you will need to return to step 1 above and create it first).

2. Select the Create new button.
   The Create participant form appears, starting from Step 1 (Details).

3. Insert a meaningful Name for the participant (e.g. "Montcliff DMV").

4. Use the Country dropdown list to select the Participant’s country (optional). Note that when selected, this value must match the Country value in the IACA certificate associated with this participant.

5. If you select a country, a State or Province dropdown list is displayed. You can use it to select the Participant’s state or province (optional). Note that when selected, this value must match the StateOrProvinceName value in the IACA certificate associated with this participant.

6. Insert the participant’s Address (optional).

7. Insert the participant’s Phone number (optional).

8. Use the Status radio button to set the participant as Active.

9. Click the Next button.
   You are directed to Step 2 (Certificates).

10. Click the Create button to create the participant.

11. Select the Issuer certificates tab.

12. Select the Add new button to add an issuer certificate for the participant.
    The Add issuer certificate form appears.

13. Upload the PEM file you want to use as this participant’s identifier for issuing mDocs (this must be a valid IACA certificate and match any values set for Country and State or Province above).
    You should now see the certificate summary and details.

14. Use the Credential types valid for field to select the credential types that this participant will be allowed to issue.

    • You can insert as many credential types as you want.
    • You can use the pre-populated options (org.iso.18013.5.1.mDL and/or org.iso.23220.photoid.1) or insert custom credential types that are relevant to your ecosystem.
    • The credential type is just a string value and does not need to match any values in the certificate. It is only used to link the participant to the credential types they are allowed to issue.

15. Scroll down and use the Status dropdown list to set the certificate as Active.

16. (Optional) To maintain trust continuity when rotating a participant's IACA certificate, expand the Link Certificate section and add this certificate as a successor to a previously uploaded certificate (refer to Linked certificates):

    • Use the Predecessor certificate dropdown to select the previous certificate that this new one succeeds. The dropdown lists the participant's existing certificates because the predecessor must already exist on your tenant before you can link to it.
    • Upload the link certificate into the Link Certificate PEM file field. The link certificate is the participant's proof that they own both the predecessor and the new certificate, which is what lets you accept the new one while preserving trust in the previous one.

    This option is only available once at least one certificate has been added for the participant.

17. Click the Add button.

Repeat the above steps for each participant you want to include in your VICAL.

Make a request of the following structure to create a participant in your ecosystem. The participant's IACA certificate and its authorized credential types are provided as a mobile identifier:

POST /v1/ecosystems/{ecosystemId}/participants

• ecosystemId : Replace with the id value obtained when you created the ecosystem.

{
  "name": "Montcliff DMV",
  "status": "Active",
  "isIssuer": true,
  "country": "US",
  "stateOrProvince": "US-XX",
  "identifiers": {
    "mobile": [
      {
        "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n",
        "status": "Active",
        "docTypes": ["org.iso.18013.5.1.mDL"]
      }
    ]
  }
}

• name : This required parameter is a meaningful name used to identify the participant.
• status : Set this to Active so the participant is included in the ecosystem policy and the VICAL. Only active participants are published.
• isIssuer : Set this to true so the participant can act as an issuer in the ecosystem.
• country : This optional parameter is the participant's Alpha 2 country code. When provided, it must match the country value in the IACA certificate.
• stateOrProvince : This optional parameter is the participant's ISO 3166-2 state or province. When provided, it must match the stateOrProvinceName value in the IACA certificate.
• identifiers.mobile : An array containing the participant's mDoc identifier(s). Each entry includes:
  • certificatePem : The PEM-encoded IACA certificate this participant uses as the trust anchor when signing mDocs. It must be a valid IACA as defined in Annex B of ISO/IEC 18013-5:2021.
  • status : Set to Active to include this certificate in the VICAL.
  • docTypes : The credential types this participant is allowed to issue with this IACA. The value is a string and does not need to match any value in the certificate.

The response will include an id property identifying the participant. Repeat this request for each participant you want to include in your VICAL.

With managed DTS certificates, MATTR VII provisions and maintains the DTS root CA and the signer certificates for you. You create and activate the DTS root CA, and MATTR VII automatically creates a signer (and its certificate) and uses it to sign trust lists as required. Managed DTS certificates always use the 2-tier model.

POST /v1/ecosystems/certificates/ca

{
  "organisationName": "Example Inc.",
  "commonName": "Example DTS CA",
  "country": "US"
}

PUT /v1/ecosystems/certificates/ca/{dtsCaCertificateId}

{
  "active": true
}

Once a managed DTS root CA is activated, MATTR VII automatically creates and uses a signer to sign trust lists as required.

With unmanaged (external) DTS certificates, you supply and maintain the full certificate chain. You generate the DTS root CA, issue and sign the VICAL Signer Certificates (VSCs), upload the root and each VSC to MATTR VII, and handle renewal and revocation.

Select the tab for the certificate model you want to configure. For guidance on choosing a model, see certificate models: 2-tier and 3-tier.

POST /v1/ecosystems/certificates/ca

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n"
}

POST /v1/ecosystems/certificates/vical-signers

{
  "caId": "080c670a-2e90-4023-b79f-b706e55e9bc6"
}

PUT /v1/ecosystems/certificates/vical-signers/{vicalSignerId}

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n"
}

PUT /v1/ecosystems/certificates/ca/{dtsCaCertificateId}

{
  "active": true
}

POST /v1/ecosystems/certificates/ca

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n",
  "useIntermediateCa": true
}

POST /v1/ecosystems/certificates/ca/{dtsCaCertificateId}/intermediate

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n",
  "usages": ["VICAL", "RICAL"]
}

POST /v1/ecosystems/certificates/vical-signers

{
  "intermediateCaId": "080c670a-2e90-4023-b79f-b706e55e9bc6"
}

PUT /v1/ecosystems/certificates/vical-signers/{vicalSignerId}

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\n...\r\n-----END CERTIFICATE-----\r\n"
}

PUT /v1/ecosystems/certificates/ca/{dtsCaCertificateId}

{
  "active": true
}

1. Navigate to the Trust lists page under the Digital Trust Service section.
2. Select the VICAL (Trusted issuers) tab.
3. Enter a meaningful Provider name to identify the provider of the VICAL. This will be included in the VICAL metadata and used by relying parties to identify the source of the VICAL.
4. Select the Create button.
5. Review the preview area where you can see all participants and credential types included in the VICAL.
6. Select Generate & Publish when you are ready.
   The VICAL is now generated and published, and a modal is displayed where you can:
   • Use the Download button to download the VICAL policy file.
   • Use the Copy button to copy a link to the public endpoint where relying parties can access the policy.

First, make a request of the following structure to update the VICAL configuration and set the VICAL provider name. A VICAL configuration is required before a VICAL can be created:

PUT /v1/ecosystems/{ecosystemId}/vicals/configuration

• ecosystemId : Replace with the id value of your ecosystem.

{
  "vicalProvider": "Example Provider"
}

• vicalProvider : This required parameter is the provider name included in the VICAL metadata and used by relying parties to identify the source of the VICAL.

Then, make a request of the following structure to create (generate and publish) a VICAL based on your ecosystem policy:

POST /v1/ecosystems/{ecosystemId}/vicals

The response includes the vicalIssueID and issuance date of the published VICAL. Relying parties can retrieve it from the public Retrieve latest VICAL endpoint:

curl -o vical-latest.cbor \
  https://your-tenant.vii.au01.mattr.global/v1/ecosystems/{ecosystemId}/vicals/public/latest

1. Return to the Trust lists page under the Digital Trust Service section.
2. Select the VICAL (Trusted issuers) tab.
3. Expand the VICAL configuration panel.
4. Use the Generation method radio button to select Auto generate.
5. Use the Auto generate frequency dropdown list to select how often you want the VICAL to be automatically generated and published (daily/weekly).
6. Select the Update button.
7. Review the preview area where you can see all participants and credential types included in the VICAL.

Note that the VICAL is not generated and published yet. It will only be generated and published automatically based on the frequency you selected in step 5 above. If you want to generate and publish the VICAL immediately, you can select the Generate & Publish button.

Make a request of the following structure to update the VICAL configuration and enable scheduled auto-publishing:

PUT /v1/ecosystems/{ecosystemId}/vicals/configuration

{
  "vicalProvider": "Example Provider",
  "autoPublish": {
    "enabled": true,
    "frequency": "Daily"
  }
}

• autoPublish.enabled : Set to true to enable scheduled automatic generation and publishing of the VICAL.
• autoPublish.frequency : Required when enabled is true. How often the VICAL is automatically generated and published. One of Daily or Weekly.

When auto-publishing is enabled, the VICAL is generated and published automatically on the schedule you set. You can still generate and publish a VICAL immediately at any time by calling the Create a VICAL endpoint.

1. Return to the Trust lists page under the Digital Trust Service section.
2. Select the VICAL (Trusted issuers) tab.
3. Scroll down and select the View Previously Published button to see all previously published VICALs.
4. Use the Download button to download the policy file for any previously published VICAL displayed.

Make a request of the following structure to retrieve all VICALs published in your ecosystem. This endpoint is public and does not require authentication:

GET /v1/ecosystems/{ecosystemId}/vicals/public

The response is a JSON list of the published VICALs with their vicalIssueID, issuance date, and filename. To download a specific VICAL policy file (a CBOR-encoded file), call the Retrieve a VICAL endpoint with the relevant vicalIssueId:

curl -o vical.cbor \
  https://your-tenant.vii.au01.mattr.global/v1/ecosystems/{ecosystemId}/vicals/public/{vicalIssueId}