How to use Status Lists

A guide on using Status Lists to manage credential status in the FortID Issuer Service.

This guide explains how to use Status Lists to track and manage the validity of Verifiable Credentials (VCs). Status Lists allow you to revoke, suspend, or reactivate credentials after they have been issued.

Introduction

Status Lists provide a mechanism for credential issuers to track the validity state of each issued credential. This is essential for credential lifecycle management, allowing you to:

Revoke compromised or invalid credentials
Temporarily suspend credentials
Restore previously suspended credentials
Signal other custom status values

When you create an issuer with the statusBits parameter, the FortID Issuer Service maintains a persistent Status List. Each issued credential is assigned a specific slot (index) in this list.

How Status Lists work

The statusBits parameter determines the "granularity" of the statuses. More bits allow for more complex states but increase the status list's data footprint.

Bits	Possible Values	Common Use Case
1 bit	0–1	Simple Binary (Valid / Revoked)
2 bits	0–3	Recommended. (Valid / Revoked / Suspended / Custom)
4 bits	0–15	Advanced lifecycle tracking
8 bits	0–255	Complex enterprise or regulatory states

Standard Status Values

While you can define custom logic, we recommend following these industry conventions:

Status 0 = VALID - The credential is currently valid and active
Status 1 = INVALID - The credential has been revoked or is invalid
Status 2 = SUSPENDED - The credential is temporarily suspended

Additional status values (3-255) can be defined based on your specific use case requirements.

Prerequisites

Before using Status Lists, ensure you have:

A valid API key for the FortID Issuer Service. See Using the API-KEY for details.
Basic understanding of the credential issuance process. See How to Issue a Verifiable Credential.

1. Create an Issuer with a Status List

To manage credential status, you must define statusBits when creating the issuer. If omitted, the issuer will not use Status Lists and issued credentials cannot be revoked later.

Request Example

curl -X POST "https://eis.fortid.com/control/issuer" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "issuerId": "university-issuer",
    "issuerMetadata": {
      "display": [
        {
          "name": "UniversityIssuer",
          "locale": "en-US",
          "background_color": "#12807c",
          "text_color": "#FFFFFF"
        }
      ]
    },
    "statusBits": 2
  }'

Parameters

issuerId (optional) - A unique identifier for the issuer. If omitted, a UUID will be generated automatically.
issuerMetadata (optional) - Display properties for the issuer that will appear in wallets.
statusBits (required for status list) - The number of bits to use for each credential status. Must be one of: 1, 2, 4, or 8. Once created they are immutable.

Note: If statusBits is not provided, the issuer will not maintain a status list, and you will not be able to update credential statuses later.

Response Example

{
  "issuerId": "university-issuer",
  "issuerPublicKey": "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE1MtHIxlGP5TARqBccrddNm1FnYH1Fp+o\nnETz5KbXPSeG5FGwKMUXGfAmSZJq2gENULFewwymt+9bTXkjBZhh8A==\n-----END PUBLIC KEY-----",
  "issuerMetadataEndpoint": "https://eis.fortid.com/protocol/oid4vci/issuer/university-issuer/.well-known/openid-credential-issuer",
}

The response confirms that the issuer has been created successfully. The issuer will now maintain a status list for all credentials it issues.

2. Issue Credentials with Status List Support

Once an issuer is created with Status List support, all credentials issued by this issuer will automatically include a reference to the status list. This allows verifiers to check the current status of the credential.

When you issue a credential, the Issuer Service automatically:

Assigns the next available index in the status list to the credential
Sets the initial status to 0 (VALID)
Includes the status list reference in the issued credential
Returns a statusPointer in the response containing the status list location

Request Example

Here's an example of issuing a Mobile Driving License (mDL) credential from an issuer with Status List support:

curl -X POST "https://eis.fortid.com/control/issuer/university-issuer/initiate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "credentialData": {
      "credentialConfigurationId": "org.iso.18013.5.1.mDL.HR",
      "claims": {
        "org.iso.18013.5.1": {
          "family_name": "Horvat",
          "given_name": "Ivan",
          "birth_date": "1985-03-15",
          "issue_date": "2024-01-10",
          "expiry_date": "2034-01-10",
          "issuing_country": "HR",
          "issuing_authority": "Ministry of Internal Affairs - Croatia",
          "document_number": "12345678",
          "portrait": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlbaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD3+iiigD//2Q==",
          "driving_privileges": [
            {
              "vehicle_category_code": "B",
              "issue_date": "2005-06-20",
              "expiry_date": "2034-01-10"
            },
            {
              "vehicle_category_code": "A",
              "issue_date": "2010-04-12",
              "expiry_date": "2034-01-10"
            }
          ],
          "un_distinguishing_sign": "HR",
          "sex": 1,
          "height": 180,
          "birth_place": "Zagreb",
          "resident_address": "Ilica 123",
          "resident_city": "Zagreb",
          "resident_postal_code": "10000",
          "resident_country": "HR"
        }
      }
    },
    "protocolConfig": {
      "grant_type": "PreAuthorizedCode"
    }
  }'

Note: This example assumes you have already assigned the mDL schema to your issuer. See How to Issue a Verifiable Credential for details on schema assignment.

Issuance Response with Status Information

When you issue a credential from a "Status-enabled" issuer, the response includes a statusPointer.

{
  "sessionId": "aabe7904-9e4b-4627-a8d3-58b739aae380",
  "authCodeOrPreAuth": {
    "grant_type": "urn:ietf:params:oauth:grant-type:pre-authorized_code",
    "pre-authorized_code": "9j0ZFupRPl9PrX6o6RTtAw",
    "tx_code": "7443"
  },
  "credentialOfferUri": "openid-credential-offer://?credential_offer_uri=https://eis.fortid.com/...",
  "statusPointer": {
    "statusListId": "50482b57-6d29-4c22-929b-d8c7ca8254e3",
    "statusListIndex": 0
  }
}

statusListId - The UUID of the status list containing this credential's status
statusListIndex - The index position (0-based) of this credential within the status list

You must store these values in your own database.

3. Update Credential Status

After a credential has been issued, you can update its status at any time using the status list endpoint. This is commonly used to revoke or suspend credentials.

Request Example

To update the status of a credential, you need the values from the statusPointer field in the issuance response (see section 2):

issuerId - The identifier of the issuer that issued the credential
listId - The statusListId from the issuance response
listIndex - The statusListIndex from the issuance response
status - The new status value to set

curl -X POST "https://eis.fortid.com/control/issuer/university-issuer/status-list/{listId}/{listIndex}" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "status": 1
  }'

Request Body

status - An integer representing the new status value. The value must be valid for the number of bits configured for the issuer:
- For 1 bit: 0 or 1
- For 2 bits: 0, 1, 2, or 3
- For 4 bits: 0 through 15
- For 8 bits: 0 through 255

Common Use Cases

Revoking a credential (set status to INVALID):

curl -X POST "https://eis.fortid.com/control/issuer/university-issuer/status-list/{listId}/{listIndex}" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "status": 1
  }'

Suspending a credential (set status to SUSPENDED):

curl -X POST "https://eis.fortid.com/control/issuer/university-issuer/status-list/{listId}/{listIndex}" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "status": 2
  }'

Reactivating a suspended credential (set status back to VALID):

curl -X POST "https://eis.fortid.com/control/issuer/university-issuer/status-list/{listId}/{listIndex}" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: HCLN4ZKnWYJAfyNkDnQ57gEAHuejD6MN" \
  -d '{
    "status": 0
  }'

4. Retrieve Status Lists

Status lists are publicly accessible to allow verifiers to check the validity of credentials. Unlike the update operation which requires an API key, retrieving Status Lists is available to anyone and does not require authentication.

Public Status List Endpoint

Status lists are served through the public OpenID4VCI protocol endpoints, not the control API. The URL format follows this pattern:

curl -X GET "https://eis.fortid.com/protocol/oid4vci/issuer/university-issuer/status-list/{listId}" \
  -H "Content-Type: application/json"

Key Points:

No API key required - This is a public endpoint
No authentication needed - Anyone can access it
Used by verifiers - To check if credentials are still valid

Response Format

The response is a compressed, encoded representation of the status list:

{
  "status_list": {
    "bits": 2,
    "lst": "H4sIAAAAAAAA...(base64-encoded compressed data)..."
  }
}

Response Fields:

bits - The number of bits per status (matches the statusBits from issuer creation)
lst - A compressed, base64-encoded bitstring containing all credential statuses

Understanding the Status List

The status list is a compact binary representation where:

Each credential occupies exactly statusBits bits
The credential at index 0 uses bits 0-1 (for 2-bit status)
The credential at index 1 uses bits 2-3 (for 2-bit status)
And so on...

Who Needs to Retrieve Status Lists?

Verifiers retrieve status lists to check credential validity:

Verifier receives a credential from a holder
Credential contains status list reference (statusListId and statusListIndex)
Verifier fetches the status list from the public URL
Verifier extracts the status at the given index
Verifier checks if status = 0 (VALID)

Note: Not all issuers treat status 0 as the only acceptable value. What constitutes a "valid" credential is defined by the issuer. Consult the issuer's specification to determine which status values should be accepted.

Issuers typically don't need to retrieve status lists because:

You control the status updates through the control API
You should maintain your own database tracking credential statuses
The public endpoint is optimized for verifier access, not issuer management

Example: Complete Status Check Flow

Here's how a verifier would check a credential's status:

When a holder presents a credential to a verifier (e.g., showing their digital driving license to verify age), the verifier receives the entire credential including the embedded status reference. The verifier then uses this information to check if the credential is still valid.

Step 1: Extract status information from the credential

Note: This status information was automatically embedded in the credential by the Issuer Service during issuance. The wallet received and stored it along with the credential data. When the holder presents the credential to a verifier, this status reference is shared with the verifier as part of the credential.

{
  "status": {
    "status_list": {
      "uri": "https://eis.fortid.com/protocol/oid4vci/issuer/university-issuer/status-list/{listId}",
      "idx": 0
    }
  }
}

Step 2: Fetch the status list

curl -X GET "https://eis.fortid.com/protocol/oid4vci/issuer/university-issuer/status-list/{listId}" \
  -H "Content-Type: application/json"

Step 3: Decompress and extract the status at index 0

Decode base64
Decompress
Extract bits at the credential's index
Interpret the value (0 = VALID, 1 = INVALID, 2 = SUSPENDED)

Best Practices

Security Considerations

Audit status changes - Maintain logs of all status updates for compliance and debugging
Consider automation - For time-based expiration or automated suspension, consider implementing scheduled status updates

Status Management Strategy

Document your status values - If using more than the standard 3 status values, document what each additional value means
Communicate revocations - Consider notifying credential holders when their credentials are revoked or suspended

Performance Considerations

Choose appropriate bit size - Don't over-allocate bits if you only need a few status values

Need additional help? Visit the full Issuer API reference.

How to use Status Lists

Introduction

How Status Lists work

Standard Status Values

Prerequisites

1. Create an Issuer with a Status List

Request Example

Parameters

Response Example

2. Issue Credentials with Status List Support

Request Example

Issuance Response with Status Information

3. Update Credential Status

Request Example

Request Body

Common Use Cases

4. Retrieve Status Lists

Public Status List Endpoint

Response Format

Understanding the Status List

Who Needs to Retrieve Status Lists?

Example: Complete Status Check Flow

Best Practices

Security Considerations

Status Management Strategy

Performance Considerations

Further Reading

On this page