Skip to main content

Revocation

All credentials issued by the mwen.io issuer are revocable. Revocation uses the W3C Bitstring Status List v1.0 standard. When you revoke a credential, the issuer flips a bit in a published status list. The next time the wallet presents that credential, it checks the status list and detects the revocation.

How revocation works​

Each issued credential contains a credentialStatus claim that points to the issuer's status list:

{
  "credentialStatus": {
    "id": "https://issuer.yourorg.com/api/status-list/1#42",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "revocation",
    "statusListIndex": "42",
    "statusListCredential": "https://issuer.yourorg.com/api/status-list/1"
  }
}

The wallet resolves statusListCredential at presentation time and checks whether bit 42 is set. If it is, the credential is considered revoked.

The status list is a publicly accessible endpoint — no authentication is required to read it. The issuer publishes one status list per tenant.

What happens in the wallet​

When the wallet detects a revoked credential:

  1. The credential in the Profile tab shows a red "Revoked" badge.
  2. The wallet skips the credential during authentication. If the user has a higher or equal trust-level credential for the same claim, it is used instead.
  3. If no valid substitute credential exists, the authentication falls back to the next available trust level (self-attested, if available).
  4. The user is not blocked from using the wallet — only the revoked credential is affected.

Revoking an individual credential​

From the admin portal:

  1. Go to Credentials → Issued.
  2. Find the credential you want to revoke (search by subject name, credential ID, or issuance date).
  3. Click Revoke.
  4. Confirm the revocation.

The bit is flipped in the status list immediately. The next time the holder's wallet checks the status (typically at presentation time), it will detect the revocation.

Revoking via the API​

Use POST /api/credentials/:credentialId/revoke with an operator session or offers:write API key:

curl -X POST https://issuer.yourorg.com/api/credentials/cred-abc-123/revoke \
  -H "Authorization: Bearer mk_live_<api-key>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "employment_terminated"}'

Response:

{
  "credentialId": "cred-abc-123",
  "revoked": true,
  "revokedAt": "2026-03-10T15:00:00Z",
  "reason": "employment_terminated"
}

The reason field is for your internal records. It is not transmitted to the wallet or visible to the holder.

Batch revocation​

For bulk operations (e.g. offboarding a cohort of employees or expiring a batch of credentials):

curl -X POST https://issuer.yourorg.com/api/credentials/revoke-batch \
  -H "Authorization: Bearer mk_live_<api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialIds": [
      "cred-abc-123",
      "cred-def-456",
      "cred-ghi-789"
    ],
    "reason": "employment_terminated"
  }'

Response:

{
  "revoked": ["cred-abc-123", "cred-def-456", "cred-ghi-789"],
  "failed": [],
  "revokedAt": "2026-03-10T15:01:00Z"
}

All bits are flipped in a single transaction. The failed array contains any IDs that could not be revoked (e.g. already revoked, not found).

Common revocation scenarios​

ScenarioAction
Employee leaves the organisationRevoke employee-identity-v1, department-access-v1, and role-credential-v1 for that employee. Use batch revocation if issuing multiple credential types.
Student did not complete degree requirementsRevoke university-diploma-v1 before issuance is completed, or immediately after if already issued.
Credential issued in errorRevoke immediately; contact the holder to let them know.
Credential expired by policy (time-limited role)Revoke at the scheduled time. Consider automating via a scheduled job that calls the batch revocation endpoint.
Government document cancelled (e.g. lost passport)Revoke passport-v1. The wallet displays the revoked badge; the holder can apply for reissuance.

Checking revocation status​

To check whether a specific credential has been revoked:

curl https://issuer.yourorg.com/api/credentials/cred-abc-123/status \
  -H "Authorization: Bearer mk_live_<api-key>"

Response:

{
  "credentialId": "cred-abc-123",
  "revoked": true,
  "revokedAt": "2026-03-10T15:00:00Z"
}

Revocation does not delete​

Revoking a credential does not delete it from the issuer's database or from the holder's wallet. The credential record remains in both places. The revocation status list bit is what changes.

This is by design: revocation history is auditable, and the holder may need the credential record for dispute resolution even after it is no longer valid.