Overview

This guide explains how to revoke the signing certificates that sit below your IACA in the chain of trust:

Document Signer Certificates (DSCs), which sign the Mobile Security Objects (MSOs) in your mDocs.
Status List Signer Certificates (SLSCs), which sign the Status Lists used for mDoc revocation.

When a signer can no longer be trusted, you revoke it so relying parties stop trusting the mDocs or Status Lists it signed. Revoking a signer publishes the certificate's serial number to the Certificate Revocation List (CRL) referenced by its issuing IACA. Verifiers that retrieve and process that CRL should treat the revoked signer, and anything it signed, as untrusted. Revocation does not delete already-issued mDocs, it withdraws trust in them at the certificate level.

For background on how the IACA, DSC, and Mobile Security Object (MSO) fit together, see Chain of trust and the Certificates overview.

When to revoke a signer

Revocation is the right tool when a signing certificate must be distrusted ahead of its natural expiry. Common scenarios include:

Key compromise: the private key associated with the signer is suspected or confirmed to be exposed. Anything signed by that key can no longer be trusted, so the signer is revoked immediately.
Role or authorization change: the signer was operated by a team, environment, or partner that is no longer authorized to issue on your behalf.
Misissuance: the signer was used to sign mDocs in error, or was misconfigured, and you want to invalidate its output.

You do not need to revoke a signer that is simply being rotated or is expiring on schedule. For managed IACAs, MATTR VII rotates Document Signers for you and selects a valid signer at signing time, so retiring an old signer does not require revocation. Revocation is for distrusting a signer before its validity period ends.

Prerequisites

Managed IACA: the Document Signer or Status List Signer you want to revoke must have been signed by a managed IACA. When using unmanaged (external) IACAs, MATTR VII does not hold the IACA private key and cannot sign a CRL for you. In that case you must revoke the signer certificate directly with the CA that issued it, following your own PKI processes.
Permissions: the API client needs the admin or issuer role.
The signer identifier: the id of the Document Signer or Status List Signer you want to revoke. You can obtain it from the response when the signer was created, or by listing your Document Signers or listing your Status List Signers.

How revocation and the CRL work

When MATTR VII creates a managed IACA, it embeds a CRL Distribution Point (CDP) in the IACA certificate. The CDP points to a public, MATTR VII hosted distribution endpoint for that IACA. You can see this in the example certificates parsed with the MATTR Labs X.509 certificate decoder linked from the Certificates overview.

When you revoke a signer:

MATTR VII adds the signer certificate's serial number to the CRL for the issuing IACA.
MATTR VII signs the CRL with the IACA key and serves it from the distribution endpoint embedded in the IACA certificate.
Verifiers that follow the CDP retrieve the IACA-signed CRL and check the serial numbers of the certificates in the mDoc chain against it.

The CRL distribution endpoint is public and does not require authentication, because relying parties must be able to reach it to validate certificates. You can retrieve the current CRL for an IACA in DER binary format:

GET /v2/credentials/mobile/iacas/{iacaId}/crl

See Retrieve IACA CRL for the full endpoint reference.

Revoke a Document Signer

Make a request of the following structure to revoke a Document Signer:

POST /v2/credentials/mobile/document-signers/{documentSignerId}/revoke

documentSignerId: Replace with the id of the Document Signer you want to revoke.

The request body is empty:

{}

{
  "revoked": true,
  "revocationDate": "2025-10-31T23:59:59Z"
}

revoked: Indicates that the Document Signer has been revoked.
revocationDate: ISO 8601 timestamp (UTC) indicating when the Document Signer was revoked.

Revocation is permanent. A signer cannot be un-revoked, and attempting to revoke a signer that is already revoked returns a 409 response. Before revoking a signer that is actively in use, make sure a valid replacement signer is available so issuance is not interrupted. For managed IACAs, MATTR VII automatically generates a suitable Document Signer at signing time when none of the existing signers meet the selection criteria.

Example: revoking a compromised signer

Suppose you operate a managed IACA and discover that the host running one of your signing integrations may have leaked a Document Signer private key. You retrieve the affected signer's id, then revoke it:

curl -X POST \
  "https://{tenant-subdomain}.vii.mattr.global/v2/credentials/mobile/document-signers/d2c9f2aa-fc69-4fbc-9b85-0c00591d72f6/revoke" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Once revoked, the DSC serial number is published to the IACA CRL. New issuance will no longer select the revoked signer (see Certificate selection), and verifiers that process the CRL should treat the mDocs it signed as untrusted.

Revoke a Status List Signer

The same model applies to Status List Signer Certificates (SLSCs), which sign the Status Lists used for mDoc revocation. If a Status List Signer is compromised or must otherwise be distrusted, you can revoke it the same way, provided it was issued under a managed IACA:

POST /v2/credentials/mobile/status-list-signers/{statusListSignerId}/revoke

As with a Document Signer, send an empty JSON object ({}) as the request body. The response mirrors the Document Signer response with a revoked flag and a revocationDate. Revocation is permanent, and revoking a Status List Signer that is already revoked returns a 409 response. Verifiers that process the CRL should treat the revoked Status List Signer, and any Status List it signed, as untrusted. See Revoke a status list signer for the full endpoint reference.

Revoking under unmanaged (external) IACAs

When your IACA is unmanaged, MATTR VII integrates the certificates you provide but does not hold the IACA private key, so it cannot sign or publish a CRL on your behalf. To distrust a signer under an unmanaged IACA, revoke the certificate directly with the CA that issued it and publish the updated, IACA-signed CRL at the location referenced in your IACA certificate. The customer remains responsible for the full lifecycle of external certificates, including renewal and revocation. For more detail, see External certificates.

How to revoke signing certificates