Skip to main content

Suspending and Revoking

Credentials issued with a revocation method can be suspended or revoked to manage their validity after issuance. Whether a credential supports suspension and/or revocation is defined by its schema.

All actions on this page use the same endpoint:

PATCH /api/credential/v1/{credentialId}/state

Suspend a credential​

Use suspension to make a credential temporarily invalid. A suspended credential can be reactivated at any time.

{
  "state": "SUSPENDED"
}

When suspending a credential, you can optionally include suspendEndDate alongside the state — a time at which the system will automatically reactivate the credential. Without this, the suspension remains in place until you manually reactivate or revoke.

{
  "state": "SUSPENDED",
  "suspendEndDate": "2026-09-01T00:00:00Z"
}
info

The LIFECYCLE_CHECK task checks suspended credentials against their suspendEndDate and reactivates them when the date has passed. Decide how often and when you want to run this check.

Reactivate a credential​

Set the state back to ACCEPTED to lift a suspension:

{
  "state": "ACCEPTED"
}

Credentials suspended with a suspendEndDate reactivate automatically at the specified time (assuming the lifecycle check runs) unless you reactivate them manually first.

Revoke a credential​

Use revocation to permanently invalidate a credential. This cannot be undone.

{
  "state": "REVOKED"
}
note

A credential in ACCEPTED state that has a revocation method cannot be deleted — use revocation instead. Credentials with no revocation method can be deleted in any state. Deletion has no impact on the holder's copy of the credential.

Batch credentials​

For batch credentials, you can act on either the parent credential or on individual batch items.

Acting on the parent​

Suspending, reactivating, or revoking the parent credential applies the action to all batch items together. This is the most straightforward approach when you want to manage the batch as a whole.

Acting on individual batch items​

You can also suspend or revoke individual batch items, for example, if a specific credential is compromised while the rest of the batch remains valid. To do this, pass the batch item's ID as {credentialId} instead of the parent's.

However, acting on individual items constrains what you can later do at the parent level. If any batch item is in a state that cannot be reversed, for example, if you revoke a single item, the parent can no longer be reactivated, since reactivation would require all items to be restorable. In general, once you have taken action on individual batch items, certain parent-level operations become unavailable.

tip

When managing a batch, prefer acting on the parent unless you have a specific reason to act on individual items. Mixing parent-level and item-level actions limits your options going forward.

Stopping issuance without suspending​

Suspension and revocation both affect the credential's current validity. If you instead want to stop a holder from getting new batch items, without impacting what they already have, set the batch parent's state to EXPIRING. See Credential Expiration for Issuers for details.

For the states a credential moves through during its lifecycle, see Credential States.