How to create a managed IACA

An IACA (Issuing Authority Certificate Authority) is a X.509 based certificate used to identify an mDoc issuer and verify the mDocs they issue.

The following guide describes how to use MATTR VII to create a managed IACA. When using managed IACAs, MATTR VII automatically handles the creation, storage, and lifecycle management of the IACA, including the private key, as well as signing and managing any Document Signer Certificates (DSCs) that are required to sign mDocs.

Request

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",
    "active": true
}

• 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 valu\e is 20 years from issuance.
• active : This optional boolean indicates whether the IACA is active or not. Only active IACAs can be used to sign mDocs. This can be used alongside the notBefore field to support IACA rotation by creating inactive IACAs and distributing them to relying parties in advance. When not provided, defaults to true.

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": true
}

• id : Unique identifier created for each IACA.
• 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.

What’s next?

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

IACAs can be distributed via different mechanisms, for example using a Verified Issuer Certificate Authority List (VICAL).

Alternatively, all active IACAs on a given tenant can be retrieved via an API request. This endpoint is publicly available by design, and can also be obtained by querying the tenant’s /.well-known/openid-credential-issuer endpoint and inspecting the mdoc_iacas_uri property in the response.