Learn how to set up a RICAL

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 and add its verifier certificate:

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 Police").

4. Use the Country dropdown list to select the participant's country (optional). When selected, this value must match the Country value in the verifier 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). When selected, this value must match the stateOrProvinceName value in the verifier certificate associated with this participant.

6. Insert the participant's Address and Phone number (optional).

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

8. Select the Next button.
   You are directed to Step 2 (Certificates).

9. Select the Create button to create the participant.

10. Select the Verifier certificates tab.

11. Select the Add new button to add a verifier certificate for the participant.
    The Add verifier certificate form appears.

12. Paste/upload the PEM-encoded Reader Root Certificate into the Certificate PEM file field.

13. Use the Status radio button to set the certificate to Active.

14. (Optional) To maintain trust continuity when rotating a participant's Reader Root 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.

15. Select the Add button.

Repeat the above steps for each relying party (verifier) you want to include in your RICAL.

First, make a request of the following structure to create a participant and mark it as a verifier:

POST /v1/ecosystems/{ecosystemId}/participants

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

{
  "name": "Montcliff Police",
  "status": "Active",
  "isVerifier": true,
  "country": "US",
  "stateOrProvince": "US-XX",
  "identifiers": {}
}

• 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 RICAL. Only active participants are published.
• isVerifier : Set this to true so the participant can act as a verifier in the ecosystem.
• country / stateOrProvince : Optional. When provided, must match the corresponding values in the verifier certificate uploaded for this participant.
• identifiers : This required parameter defines the participant's credential-format identifiers. For a verifier participant, pass an empty object ({}), as the Reader Root Certificate is added separately in the next request.

The response includes the participant id. Then, make a request of the following structure to create a verifier certificate for the participant. This is the Reader Root Certificate that will be included in the RICAL:

POST /v1/ecosystems/{ecosystemId}/participants/{participantId}/verifier-certificates

• participantId : Replace with the id value obtained when you created the participant.

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICTDCCAfKgAwIBAgIKeKcjIBGvXfS/sjAKBggqhkjOPQQDAjAwMQswCQYDVQQG\r\nEwJVUzEhMB8GA1UEAwwYRXhhbXBsZSBWZXJpZmllciByb290IENBMB4XDTI1MDgy\r\nNzIxMzMxNFoXDTMwMDgyNjIxMzMxNFowMDELMAkGA1UEBhMCVVMxITAfBgNVBAMM\r\nGEV4YW1wbGUgVmVyaWZpZXIgcm9vdCBDQTBZMBMGByqGSM49AgEGCCqGSM49AwEH\r\nA0IABNJHM5ZE+fpVn7b9WwjVBiOiZq9eNXq1JkNj/6ZLe+2GkaRY/WE2Xbg7yx++\r\nh3QEdX3sGKzGO7dygQALBe/4qEyjgfMwgfAwHQYDVR0OBBYEFK8ogqdUH2vZlC1y\r\nNf619a8fnx8KMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEAMHsG\r\nA1UdHwR0MHIwcKBuoGyGamh0dHBzOi8vbGVhcm4udmlpLmF1MDEubWF0dHIuZ2xv\r\nYmFsL3YyL3ByZXNlbnRhdGlvbnMvY2VydGlmaWNhdGVzL2Q3YzE3ODI4LThkMTgt\r\nNDYyZS1iNDk3LWNjNjI2NWM4ZmQxYi9jcmwwLgYDVR0SBCcwJYYjaHR0cHM6Ly9s\r\nZWFybi52aWkuYXUwMS5tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSAAwRQIhAOqD\r\n0DF3rohBitl5jAj6x1164uGGj6yAhF/eE4aJeGc+AiAgaUYHzobzaPEWd+jZOh/A\r\nq8WgVJ+8sLx9WdJDs9/shQ==\r\n-----END CERTIFICATE-----\r\n",
  "status": "Active"
}

• certificatePem : This required parameter contains the PEM-encoded Reader Root Certificate. It becomes immutable once the certificate is created.
• status : Set to Active to include this certificate in the RICAL.

Note that, unlike an issuer certificate in a VICAL, a verifier certificate does not take a docTypes array. Repeat this request for each relying party (verifier) you want to include in your RICAL.

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 RICAL Signer Certificates (RSCs), upload the root and each RSC 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/rical-signers

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

PUT /v1/ecosystems/certificates/rical-signers/{ricalSignerId}

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIDXTCCAkWgAwIBAgIJAL5...\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/rical-signers

{
  "intermediateCaId": "c1bbe671-21f8-5358-9537-eed4669b43f3"
}

PUT /v1/ecosystems/certificates/rical-signers/{ricalSignerId}

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIDXTCCAkWgAwIBAgIJAL5...\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 RICAL (Trusted verifiers) tab.
3. Enter a meaningful Provider name to identify the provider of the RICAL. This is included in the RICAL metadata and used by wallets to identify the source of the RICAL.
4. Select the Create button.
5. Review the preview area where you can see all Reader Root Certificates included in the RICAL.
6. Select Generate & Publish when you are ready.
   The RICAL is now generated and published, and a modal is displayed where you can:
   • Use the Download button to download the RICAL file (CBOR).
   • Use the Copy button to copy a link to the public endpoint where wallets can access the RICAL.

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

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

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

{
  "ricalProvider": "Example Provider"
}

• ricalProvider : This required parameter is the provider name included in the RICAL metadata and used by wallets to identify the source of the RICAL.

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

POST /v1/ecosystems/{ecosystemId}/ricals

The response includes the ricalIssueID and issuance date of the published RICAL. Wallets can retrieve it from the public Retrieve latest RICAL endpoint:

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

1. Return to the Trust lists page under the Digital Trust Service section.
2. Select the RICAL (Trusted verifiers) tab.
3. Expand the RICAL 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 RICAL to be automatically generated and published (daily/weekly).
6. Select the Update button.
7. Review the preview area where you can see all Reader Root Certificates included in the RICAL.

Note that the RICAL 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 RICAL immediately, you can select the Generate & Publish button.

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

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

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

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

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

1. Return to the Trust lists page under the Digital Trust Service section.
2. Select the RICAL (Trusted verifiers) tab.
3. Scroll down and select the View Previously Published button to open the Previously generated RICAL view, which lists each RICAL with its Issue ID, Generated at time, File name, Trigger method, and Status.
4. Use the Download button to download any previously published RICAL.

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

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

The response is a JSON list of the published RICALs with their ricalIssueID, issuance date, and filename. To download a specific RICAL file (a CBOR-encoded file), call the Retrieve specific RICAL endpoint with the relevant ricalIssueId:

curl -o rical.cbor \
  https://your-tenant.vii.au01.mattr.global/v1/ecosystems/{ecosystemId}/ricals/public/{ricalIssueId}