How to configure holder certificates

Create a managed Holder root CA

Make a request of the following structure to create a managed Holder root CA:

POST /v1/holder/certificates/ca

{
  "commonName": "Example Holder root CA",
  "country": "NZ"
}

• commonName : This optional parameter indicates the common name of the Holder root CA certificate. When specified, the value must be a valid PrintableString and cannot be an empty string. If not provided, the value defaults to {tenantDomain} Wallet Attestation.
• country : This optional parameter indicates the holder country. When specified, the value must be a valid country code as per ISO 3166-1.

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

The Holder root CA is always created as inactive. You will activate it in the next step.

Activate the Holder root CA

Make a request of the following structure to update the Holder root CA and activate it:

PUT /v1/holder/certificates/ca/{certificateId}

• certificateId : Replace with the id value obtained when you created the Holder root CA.

{
  "active": true
}

Setting active: true deactivates any previously active Holder root CA for the tenant (only one can be active at a time).

Once a managed Holder root CA is activated, MATTR VII automatically provisions wallet attestation signers on demand when the first wallet attestation request is made. No additional configuration is required.

Generate a self-signed root certificate (Holder root CA)

Use your preferred cryptographic library or tool to generate a self-signed root certificate (Holder root CA). This certificate will later be used to sign wallet attestation signer certificates.

When using unmanaged (external) certificates, you assume full responsibility for the secure management of the root certificate 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 your behalf.

Register the external Holder root CA certificate with MATTR VII

Make a request of the following structure to create an unmanaged Holder root CA:

POST /v1/holder/certificates/ca

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICAzCCAaqgAwIBAgIJAKFOoPvy+rfbMAoGCCqGSM49BAMCMCUxCzAJBgNVBAYT\r\nAk5aMRYwFAYDVQQDDA1NQVRUUiBFeGFtcGxlMB4XDTI2MDUxNDAwMjEzNVoXDTM2\r\nMDUxMTAwMjEzNVowJTELMAkGA1UEBhMCTloxFjAUBgNVBAMMDU1BVFRSIEV4YW1w\r\nbGUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATTSjjTuOouwLNObXEwm0TNNWu5\r\nQfuWW1aMaIz/SwzKfHEP8A4fAgiEYF5SfO5Fy+cQ8m159e3go7yAzmyE1zgIo4HC\r\nMIG/MBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQW\r\nBBQ8paHD6yC0HheUE53YCRx1fR/8JzB6BgNVHR8EczBxMG+gbaBrhmlodHRwczov\r\nL2V4YW1wbGUuY29tL3YyL2NyZWRlbnRpYWxzL2hvbGRlci93YWxsZXQtYXR0ZXN0\r\nYXRpb24vY2FzLzJlODljMTU2LTMxZDUtNDc4My1iZDU5LTkwNTViNWY4ZTdkMi9j\r\ncmwwCgYIKoZIzj0EAwIDRwAwRAIgJkH+qkQ4Rz//MBU61u3fDZOrHYejR2FIK1Lv\r\nIEiNRDACIHePIX2AEK0Ls6wIxgyJt4hdj64QSSzH1hJzMPGGFyM9\r\n-----END CERTIFICATE-----\r\n"
}

• certificatePem : This required parameter contains the PEM-encoded Holder root CA certificate. The certificate must be valid and not expired.

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

Create a wallet attestation signer

Make a request of the following structure to create a wallet attestation signer that references the unmanaged Holder root CA:

POST /v1/holder/certificates/wallet-attestation-signers

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

• caId : Replace with the id value obtained when you created the unmanaged Holder root CA in the previous step. Attempts to provide a managed Holder root CA identifier for manual wallet attestation 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 wallet attestation signer. This identifier is used in subsequent operations to reference this signer.
• csrPem : The X.509 Certificate Signing Request (CSR) in PEM format. You will use this CSR to generate a valid wallet attestation signer certificate in the next step.

Generate and sign the wallet attestation signer certificate

Use your preferred cryptographic library or tool to generate and sign a wallet attestation signer certificate using the CSR provided in the response from the previous step. The certificate must be signed by your Holder root CA.

Associate the certificate with the wallet attestation signer

Make a request of the following structure to update the wallet attestation signer to upload the signed certificate and activate the signer:

PUT /v1/holder/certificates/wallet-attestation-signers/{certificateId}

• certificateId : Replace with the id value obtained when you created the wallet attestation signer in the previous step.

{
  "active": true,
  "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICRjCCAe2gAwIBAgIJAMaBeZ37qSVQMAoGCCqGSM49BAMCMCUxCzAJBgNVBAYT\r\nAk5aMRYwFAYDVQQDDA1NQVRUUiBFeGFtcGxlMB4XDTI2MDUxNDAwMjEzNVoXDTI3\r\nMDUxNDAwMjEzNVowTTELMAkGA1UEBhMCTloxPjA8BgNVBAMMNU1BVFRSIEV4YW1w\r\nbGUgV2FsbGV0IEF0dGVzdGF0aW9uIFNpZ25lciAxNzc4NzE2ODAwMDAwMFkwEwYH\r\nKoZIzj0CAQYIKoZIzj0DAQcDQgAE2bX0ZXV2DyFj3d1Va98s4PiBMN48ZFCf2dQZ\r\nl6Y/lIZfQQjQcIEWi+dKAsYyaqeUi81yxzvXfmRogVh9nweQoaOB3TCB2jAMBgNV\r\nHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDAdBgNVHQ4EFgQUQ3gaPaANZ83EHYNE\r\nrgjFP8z3VtowHwYDVR0jBBgwFoAUPKWhw+sgtB4XlBOd2AkcdX0f/CcwegYDVR0f\r\nBHMwcTBvoG2ga4ZpaHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9o\r\nb2xkZXIvd2FsbGV0LWF0dGVzdGF0aW9uL2Nhcy8yZTg5YzE1Ni0zMWQ1LTQ3ODMt\r\nYmQ1OS05MDU1YjVmOGU3ZDIvY3JsMAoGCCqGSM49BAMCA0cAMEQCICdeu9XvaCqW\r\nYwkST+wYtrm4awOt+mRQwqrMMVjAQj1BAiBgdrg0JeXyofGrZvb34TEM/gQDi/HV\r\nHCqUhEUm9T92pw==\r\n-----END CERTIFICATE-----\r\n"
}

• active : Set to true to activate the signer. Can only be set to true when a certificatePem is provided. Only active wallet attestation signers can be used to sign wallet attestation JWTs.
• certificatePem : The PEM-encoded certificate signed by your Holder root CA. This field is immutable after the first upload — subsequent PUT requests may only toggle active.

Activate the Holder root CA

Make a request of the following structure to update the Holder root CA and activate it:

PUT /v1/holder/certificates/ca/{certificateId}

• certificateId : Replace with the id value obtained when you registered the unmanaged Holder root CA.

{
  "active": true
}

Wallet Attestation is ready

Once the Holder root CA and wallet attestation signer are activated, they are used to sign wallet attestation JWTs. When a holder application with SDK Tethering configured requests a Wallet Attestation token, the tethered MATTR VII automatically selects a valid and active wallet attestation signer to sign the JWT.

If there is no valid and active wallet attestation signer, MATTR VII will return an error. Unlike the managed flow, MATTR VII does not automatically create new wallet attestation signers in the unmanaged flow, and you are responsible for manually creating and uploading them as needed.