Skip to main content

Revoke Credentials

This section explains how to revoke verifiable credentials using Skippy's platform. Credential revocation is the process of marking issued credentials as invalid, ensuring they fail verification checks even while remaining cryptographically valid.

Understanding the Revocation Workflow​

Credential Revocation Flow

The credential revocation process follows the SD-JWT Status List specification, which provides an efficient, privacy-preserving method for credential status management using bitstring-based status lists.

What is a Status List?​

A status list is a compressed bitstring where each bit represents the revocation status of a credential. Think of it as a massive array where each position (index) corresponds to a specific credential.

How Status Lists Work​

  1. Allocation - When a credential is issued, it's assigned a unique index in a status list
  2. Binding - The credential is linked to its status list and index via metadata
  3. Checking - Verifiers fetch the status list and check the bit at the credential's index
  4. Revocation - Setting the bit from 0 to 1 marks the credential as revoked
  5. Distribution - Status lists are served as signed JWTs for authenticity

Status List URI Format​

https://agent.skippy.id/statuslist/{listId}

This URI provides:

  • A compressed bitstring of credential statuses
  • Cryptographic signature by the issuer's DID
  • Cacheable format for efficient verification

When is a Credential Actually Revoked?​

The credential becomes revoked when the status list bit is flipped from 0 to 1. This happens when:

  1. You click "Revoke" on the credential in the dashboard
  2. The system updates the status list by setting the credential's index bit to 1
  3. The status list invalidates its cache and generates a new signed JWT
  4. Verifiers check the updated status and see the credential is revoked

This means revocation is immediate and effective once the status list is updated. This approach:

  • Provides instant revocation without modifying the credential
  • Preserves holder privacy (verifiers can't identify which credential was checked)
  • Enables efficient batch status checks
  • Works with any credential stored in any wallet

The Complete Revocation Flow​

Step 1: Credential Issued with Status Metadata (Issuer)​

  • Credential issued with status list reference
  • Contains: status_list_url, status_list_index, status_purpose
  • Status bit initialized to 0 (active)

Step 2: Monitor Status (Holder/Verifier)​

  • Credential holder stores credential in wallet
  • Status metadata embedded in credential
  • Can check status at any time

Step 3: Trigger Revocation (Issuer)​

  • Navigate to credential in dashboard
  • Click "Revoke Credential" button
  • Confirm revocation action

Step 4: Update Status List (System)​

  • Locate status list and credential index
  • Flip bit from 0 to 1 at credential's index
  • Update StatusBinding record with timestamp
  • Invalidate cached status list JWT

Step 5: Verification Fails (Verifier → Holder)​

  • Verifier requests credential presentation
  • Fetches status list from embedded URL
  • Checks bit at credential's index
  • Finds bit = 1, marks credential as revoked
  • Rejects verification request

Prerequisites​

Before you can revoke credentials, you need:

  1. An Issued Credential - Credential must be successfully issued with status metadata
  2. Status List Metadata - Credential includes status list reference (automatically added)
  3. Project Access - Appropriate permissions to revoke credentials in your project

Revocation States​

Throughout the credential lifecycle, credentials can have these statuses:

  • Active - Credential issued, status bit = 0
  • Revoked - Credential revoked, status bit = 1
  • Expired - Credential past expiration date (independent of revocation)

Learn more about credential states →

Revocation vs. Expiration​

Expiration​

  • Credentials expire automatically based on their exp claim
  • No action required - time-based automatic invalidation
  • Expired credentials fail verification
  • Expiration is embedded in the credential itself

Revocation​

  • Revocation is a deliberate issuer action
  • Revoked credentials fail verification immediately
  • Revocation can happen at any time, before or after expiration
  • Revocation is permanent and cannot be undone
  • Stored in external status list, not in credential