Create an IACA

An IACA (Issuing Authority Certificate Authority) is a X.509 based certificate used to identify a Mobile Credential issuer and verify the Mobile Credentials they issue. An IACA is used to sign Document Signer Certificates (DSC), which are then in turn used to sign Mobile Security Objects (MSO) in Mobile Credentials. Refer to chain of trust for more information.

There can be only one IACA per MATTR VII tenant. The private key linked to the certificate is stored and managed in the highly secure and reliable Key Management System (KMS).

Request

Make the following request to create an IACA:

http
Copy to clipboard.
1POST /v2/credentials/mobile/iacas
json
Copy to clipboard.
1{
2	"country": "NZ",
3	"commonName": "MATTR IACA",
4	"notAfter": "2034-09-26"
5}
  • 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 alpha-2.

  • commonName: This optional parameter indicates the common name of the IACA certificate. When specified, the value must be a valid PrintableString. If not provided and a custom domain is configured and verified, the custom domain is used. If no custom domain is configured, the tenant subdomain is used.

  • notAfter: This optional parameter is used to set the IACA expiry date. When not provided, defaults to 10 years from issuance.

Response

json
Copy to clipboard.
1{
2    "id": "e86dd9bc-1414-4f60-aeb1-9143451424bb",
3    "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",
4    "certificateData": {
5        "notAfter": "2034-09-26T00:09:21.000Z",
6        "notBefore": "2023-08-08T00:09:21.000Z",
7        "commonName": "MATTR IACA",
8        "country": "NZ"
9    },
10    "certificateFingerprint": "57b178a6c2b8c1877dba515ad4fd60f9c805efc309287182db7debfe43a22928",
11    "publicKeyJwk": {
12        "kty": "EC",
13        "crv": "P-256",
14        "x": "kbuvX83YDOKHZMj7UXGXd3hlgsOAQe0rWTRkZriJa60",
15        "y": "pTK_1JY8eBRiNiZEHWDsRHOP-k5ICymTvVj5AD6P2c8"
16    }
17}
  • id: Unique identifier created for each IACA.

  • certificatePEM: Certificate PEM format.

  • certificateData: Key details of the created IACA:

    • notAfter: IACA's expiry date (defaults to 10 years from issuance when not provided in the request).

    • notBefore: IACA’s active from date.

    • commonName: IACA's name, based on the request above.

    • country: IACA’s issuer country, based on the request above.

  • certificateFingerprint: Hashed value of the IACA certificate that includes all certificate data and its signature.

  • publicKeyJwk: JWK format of the IACA public key.

What's Next?

  • Once an IACA is created on a MATTR VII tenant, it can be retrieved via an API request. This endpoint is publicly available by design, as it enables a relying party to use the IACA to verify a signed Mobile Credential. This endpoint can be obtained by querying the tenant's /.well-known/openid-credential-issuer endpoint and inspecting the mdoc_iacas_uri property in the response.

  • Once an IACA is created on a MATTR VII tenant, you can use it to create a Document Signer Certificate.