How to create issuer certificates

Create a managed IACA

Make a request of the following structure to create a managed IACA:

POST /v2/credentials/mobile/iacas

{
  "commonName": "Example IACA",
  "country": "US",
  "stateOrProvinceName": "US-AL",
  "notBefore": "2024-09-26",
  "notAfter": "2034-09-26"
}

• commonName : This optional parameter indicates the common name of the IACA certificate. When specified, the value must be a valid PrintableString and cannot be an empty string. If not provided and a custom domain is configured and verified, the custom domain is used followed by the word IACA. If no custom domain is configured, the tenant subdomain is used instead.
• country : This optional parameter indicates the issuer country. If not provided, a country is selected based on the region of the tenant subdomain cloud host. When specified, the value must be uppercase and a valid country code as per ISO 3166-1.
• stateOrProvinceName: This optional parameter indicates the issuer state or province. When specified, the value must be uppercase and a valid country code as per ISO 3166-2.
• notBefore : This optional parameter is used to set when the IACA becomes valid and can be used to sign mDocs. This can be used alongside the active field to support IACA rotation by creating inactive IACAs and distributing them to relying parties in advance. When not provided, defaults to time of creation.
• notAfter : This optional parameter is used to set the date and time when the IACA expires. When not provided, defaults to 10 years from notBefore, or from issuance if notBefore is not provided. Maximum value is 20 years from issuance.

Response

{
  "id": "e86dd9bc-1414-4f60-aeb1-9143451424bb",
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIIBwzCCAWigAwIBAgIKRGC+CqoTGJKkkTAKBggqhkjOPQQDAjAgMR4wCQYDVQQG\r\nEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwHhcNMjMwODA4MDAwOTIxWhcNMzMwODA1\r\nMDAwOTIxWjAgMR4wCQYDVQQGEwJOWjARBgNVBAMTCk1BVFRSIElBQ0EwWTATBgcq\r\nhkjOPQIBBggqhkjOPQMBBwNCAASRu69fzdgM4odkyPtRcZd3eGWCw4BB7StZNGRm\r\nuIlrraUyv9SWPHgUYjYmRB1g7ERzj/pOSAspk71Y+QA+j9nPo4GJMIGGMBIGA1Ud\r\nEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgAGMB0GA1UdDgQWBBSONcHGh4If\r\nO1dYorRpsuFrs+f8SDAcBgNVHRIEFTATgRFpbmZvQG1hdHRyLmdsb2JhbDAjBgNV\r\nHR8EHDAaMBiiFoYUaHR0cHM6Ly9tYXR0ci5nbG9iYWwwCgYIKoZIzj0EAwIDSQAw\r\nRgIhAPKJIGDSvp7VxRBLCWWeghqi8UUeO+dZsC49TUZcDMNxAiEAoh+7dT+l+GzX\r\nk0J2SoGmPiagrbAuIYyTHwzZZuYr1W4=\r\n-----END CERTIFICATE-----\r\n",
  "certificateData": {
    "commonName": "Example IACA",
    "country": "US",
    "stateOrProvinceName": "US-AL",
    "notBefore": "2024-09-26T00:09:21.000Z",
    "notAfter": "2034-09-26T00:09:21.000Z"
  },
  "certificateFingerprint": "57b178a6c2b8c1877dba515ad4fd60f9c805efc309287182db7debfe43a22928",
  "publicKeyJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "kbuvX83YDOKHZMj7UXGXd3hlgsOAQe0rWTRkZriJa60",
    "y": "pTK_1JY8eBRiNiZEHWDsRHOP-k5ICymTvVj5AD6P2c8"
  },
  "active": false,
  "isManaged": true
}

• id : Unique identifier created for each IACA. You will use it to activate the IACA in the next step.
• certificatePEM : Certificate PEM format.
• certificateData : Key details regarding the created IACA:
  • commonName : IACA's name, as provided in the request.
  • country : IACA’s issuer country, as provided in the request.
  • stateOrProvinceName : IACA’s issuer state/province, as provided in the request.
  • notBefore : Data and time when IACA becomes valid.
  • notAfter : Date and time when IACA expires.
• certificateFingerprint : Hashed value of the IACA certificate that includes all certificate data and its signature.
• publicKeyJwk : JWK format of the IACA public key.
• active: IACA status. IACAs are always created as inactive, meaning they cannot be used to sign mDocs until they are activated. This is useful for IACA rotation, allowing you to create a new IACA in advance and distribute it to relying parties before it becomes active.
• isManaged : Indicates that this is a managed IACA.

Activate the IACA

Make a request of the following structure to update the unmanaged IACA and activate it:

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

• iacaId : Replace with the id value obtained when you registered the unmanaged IACA.

{
  "active": true
}

Once a managed IACA is activated, MATTR VII will automatically use it to sign DSCs required to sign mDocs. Refer to Certificate selection for signing mDocs for more information.

Generate a self-signed root certificate (IACA)

Use your preferred cryptographic library or tool to generate a self-signed root certificate (IACA). This certificate will be used to sign the Document Signer Certificates (DSCs) for mDoc issuance. Ensure the IACA meets the requirements specified in ISO/IEC 18013-5:2021 Annex B.1.2.

When using unmanaged (external) certificates, the issuer assumes full responsibility for the secure management of the uploaded root certificates and all subordinate certificates. This includes ensuring the protection, proper issuance, and timely revocation of certificates under the uploaded root, as MATTR VII does not manage or monitor these certificates on the issuer's behalf.

Register the unmanaged IACA with MATTR VII

Make a request of the following structure to create an unmanaged IACA:

POST /v2/credentials/mobile/iacas

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0zMzA5\r\nMDgyMzM0MjJaMCIxIDAJBgNVBAYTAk5aMBMGA1UEAxMMRXhhbXBsZSBJQUNBMFkw\r\nEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBbK7JKKFMWuu8kHQK2qaML+MQ0Ykk3Qg\r\n/p3TC6lQKvYJozPSpLXbJQIzMPq9u/dG+j4vq1iX/G/jFIwfiEiKEqOB0TCBzjAS\r\nBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIABjAdBgNVHQ4EFgQU9zTh\r\nKsqFxAgRJDDGW1au+ewJK6owHgYDVR0SBBcwFYYTaHR0cHM6Ly9leGFtcGxlLmNv\r\nbTBpBgNVHR8EYjBgMF6gXKBahlhodHRwczovL2V4YW1wbGUuY29tL3YyL2NyZWRl\r\nbnRpYWxzL21vYmlsZS9pYWNhcy8yZTg5YzE1Ni0zMWQ1LTQ3ODMtYmQ1OS05MDU1\r\nYjVmOGU3ZDIvY3JsMAoGCCqGSM49BAMCA0gAMEUCIQDD+eU8iOsYYC0v41L94fhF\r\nZ0brPo4gx2aRxrhE3NLFpwIgIgHCPBXJ+JICJg3K7dEsr153So4SEZzAA1rRn4eF\r\nvkM=\r\n-----END CERTIFICATE-----\r\n"
}

• certificatePem : This required parameter contains the PEM-encoded IACA certificate. The certificate must meet the following requirements:
  • Valid
  • Not expired
  • Compliant with ISO/IEC 18013-5:2021 Annex B.1.2

The response will include an id property, which is a unique identifier for the unmanaged IACA. This identifier will be used in subsequent operations to reference this unmanaged IACA.

Create a Document Signer

Make a request of the following structure to create a Document Signer that references the unmanaged IACA:

POST /v2/credentials/mobile/document-signers

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

• iacaId : Replace with the id value obtained when you created the unmanaged IACA in the previous step. Attempts to provide a managed IACA identifier for manual Document Signer creation will result in an error.

The response will include two properties which you will use later in this guide:

• id : The unique identifier for the Document Signer. This identifier will be used in subsequent operations to reference this Document Signer.
• csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid Document Signer Certificate in the next step.

Generate and sign the Document Signer Certificate (DSC)

Use your preferred cryptographic library or tool to generate and sign a Document Signer Certificate (DSC) using the CSR provided in the response from the previous step. Refer to the certificate requirements section in the external issuer certificates documentation for details on how to structure a valid DSC.

Associate the DSC with the Document Signer

Make a request of the following structure to update the Document Signer to activate and associate it with the generated DSC:

PUT /v2/credentials/mobile/document-signers/{documentSignerId}

• documentSignerId : Replace with the id value obtained when you created the Document Signer in the previous step.

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\r\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\r\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\r\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\r\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\r\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\r\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\r\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\r\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\r\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\r\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\r\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\r\nIavC\r\n-----END CERTIFICATE-----\r\n"
}

• active : This required boolean indicates whether the Document Signer is active or not. Can only be set to true when a certificatePem is provided. Only active Document Signers can be used to sign mDocs.
• certificatePem : This required parameter contains the PEM-encoded DSC created in the previous step.

Create a Status List Signer

Make a request of the following structure to create a Status List Signer that references the unmanaged IACA:

POST /v2/credentials/mobile/status-list-signers

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

• iacaId : Replace with the id value obtained when you created the unmanaged IACA in the previous step. Attempts to provide a managed IACA identifier for manual Status List Signer creation will result in an error.

The response will include two properties which you will use later in this guide:

• id : The unique identifier for the Status List Signer. This identifier will be used in subsequent operations to reference this Status List Signer.
• csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid Document Signer Certificate in the next step.

Generate and sign the Status List Signer Certificate (SLSC)

Use your preferred cryptographic library or tool to generate and sign a Status List Signer Certificate (SLSC) using the CSR provided in the response from the previous step. Refer to the certificate requirements section in the external issuer certificates documentation for details on how to structure a valid SLSC.

Associate the SLSC with the Status List Signer

Make a request of the following structure to update the Status List Signer to active and associate it with the Status List Signer:

PUT /v2/credentials/mobile/status-list-signers/{statusListSignerId}

• statusListSignerId : Replace with the id value obtained when you created the Status List Signer in the previous step.

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\r\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\r\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\r\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\r\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\r\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\r\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\r\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\r\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\r\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\r\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\r\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\r\nIavC\r\n-----END CERTIFICATE-----\r\n"
}

• active : This required boolean indicates whether the Status List Signer is active or not. Can only be set to true when a certificatePem is provided. Only active Status List Signers can be used to sign mDocs.
• certificatePem : This required parameter contains the PEM-encoded Status List Signer Certificate (SLSC) created in the previous step.

Activate the IACA

Make a request of the following structure to update the unmanaged IACA and activate it:

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

• iacaId : Replace with the id value obtained when you registered the unmanaged IACA.

{
  "active": true
}

Credential issuance

Signing the mDoc

Once the Document Signer and IACA are activated, they can be used to sign mDocs. MATTR VII will automatically select a valid Document Signer based on the certificate selection logic.

If there is no Document Signer that meets the selection criteria, MATTR VII will return an error stating that no valid Document Signer is available for signing. For example, if you attempt to sign an mDoc with an expiry date later than the notAfter date of all available Document Signers, MATTR VII will not find a suitable Document Signer and will return an error.

Unlike the managed IACA flow, MATTR VII does not automatically create new Document Signers in the unmanaged flow, and the issuer is responsible for manually creating and uploading them as needed.

Signing the Status List Token

If the issued mDoc is configured as revocable, it will be associated with a Status List. MATTR VII will then automatically attempt to sign a Status List Token for that Status List using an appropriate Status List Signer. The Status List Signer is selected according to the following criteria:

• The Status List Signer must be active.
• The Status List Signer must reference the same IACA as the Document Signer used to sign the mDoc.

If there is no Status List Signer that meets the selection criteria, MATTR VII will return an error stating that no valid Status List Signer is available for signing. For example, if you attempt to sign an mDoc using a Document Signer that was created with an IACA that does not have an active Status List Signer, MATTR VII will not find a suitable Status List Signer and will return an error.

Unlike the managed IACA flow, MATTR VII does not automatically create new Status List Signers in the unmanaged flow, and the issuer is responsible for manually creating and uploading them as needed.