Status lists

Credential status lists are utilized to perform credential suspension or revocation after the initial credential issuance, or to indicate some arbitrary status associated with the credential.

This can be useful, for example, to revoke a mis-issued credential, a credential with invalid data, or any other already existing credential issued from your organization.

Custom status lists, which support up to 256 arbitrary status list values, may be used to associate some custom status value to a credential.

Different credential kinds utilize different status list kinds, but Document Rails provides a unified API for managing all status lists.

Supported status list kinds:

Name	Kind identifier
W3C	1
IETF TSL	2

IETF TSL supports only revocation status lists

Unlike W3C status lists, IETF TSL support is limited to revocation-only status lists. This may change in the future.

For more information about credential kind specifics, refer to the credential kind documentation:

Name	Documentation
W3C	Link
MDoc	Link
SD-JWT	Link

Sync

Built-in publisher

By default, Document Rails utilizes its own API to publish status lists.

This method doesn't require any additional setup and is enabled by default if your organization doesn't have the slp_url configuration option set.

Custom status list publishers

For improved security and performance, we provide a separate "status list publisher" server, which is meant to be publicly deployed.

Our hosted Document Rails solution features a simple way to automatically publish status lists.

Document Rails invokes the status list sync process as necessary, automatically scheduling it when new status lists are created or when a credential gets revoked.

Status list sync happens in the background in queued manner, so you may not immediately receive new updates.

To facilitate connections to your "status list publisher" server, Document Rails requires you to provide the slp_url value in the organization options:

New organization (JavaScript)Existing organization (JavaScript)

import { createOrganization } from "@vaultie/document-rails";

const response = await createOrganization(client, accessToken, {
    // ...

    // Status list publisher URL.
    slp_url: "https://slp.example.com"
});

import { updateOrganization } from "@vaultie/document-rails";

const response = await updateOrganization(client, accessToken, organizationId, {
    // ...

    // Status list publisher URL.
    slp_url: "https://slp.example.com"
});

Management

Automatic

To simplify status lists, Document Rails features an automatic management mode.

In this mode, existing revocation status lists that match output credentials will be automatically selected. If all revocation status lists are exhausted, a new status list of the required kind will be created.

To enable automatic management mode, configure auto_status_list to be true in the organization options:

New organization (JavaScript)Existing organization (JavaScript)

import { createOrganization } from "@vaultie/document-rails";

const response = await createOrganization(client, accessToken, {
    // ...

    // Enable automatic status list management.
    auto_status_list: true,
});

import { updateOrganization } from "@vaultie/document-rails";

const response = await updateOrganization(client, accessToken, organizationId, {
    // ...

    // Enable automatic status list management.
    auto_status_list: true,
});

Manual

Manual status management requires creating new status lists when all existing ones are exhausted or there are no status lists attached to the current organization.

During the printing process, you are required to provide status list identifiers to tie output credentials to.

Create new revocation status list (JavaScript)Create new suspension status list (JavaScript)Create new custom status list (JavaScript)

import { createStatusList, StatusListKind } from "@vaultie/document-rails";

const response = await createStatusList(
    client,
    accessToken,
    organizationId,
    {
        // Create a W3C status list.
        //
        // Refer to the table above for more information about existing status list kinds.
        kind: StatusListKind.W3C,

        // Unique status list identifier.
        external_id: "ExampleStatusList"
    }
);

import { createStatusList, StatusListKind, StatusListPurpose } from "@vaultie/document-rails";

const response = await createStatusList(
    client,
    accessToken,
    organizationId,
    {
        // Create a W3C status list.
        //
        // Refer to the table above for more information about existing status list kinds.
        kind: StatusListKind.W3C,

        // Unique status list identifier.
        external_id: "ExampleStatusList",

        // Set the status list purpose to suspension.
        purpose: StatusListPurpose.Suspension,
    }
);

import { createStatusList, StatusListKind, StatusListPurpose } from "@vaultie/document-rails";

const response = await createStatusList(
    client,
    accessToken,
    organizationId,
    {
        // Create a W3C status list.
        //
        // Refer to the table above for more information about existing status list kinds.
        kind: StatusListKind.W3C,

        // Unique status list identifier.
        external_id: "ExampleStatusList",

        // Set the status list purpose to custom.
        purpose: StatusListPurpose.Custom,

        // A list of supported custom values.
        //
        // This cannot be changed after the status list creation.
        values: [
            // Values should be unique and should not exceed 255.
            //
            // Description value may be embedded within the credential,
            // so its size should be consider when embedding credentials
            // into QR codes and barcodes.
            { value: 0, description: "Pending" },
            { value: 1, description: "Active" },
            { value: 100, description: "Unknown" },
        ],
    }
);

Entry update

Revoke a credential (JavaScript)Suspend a credential (JavaScript)Unsuspend a credential (JavaScript)Set custom status list value (JavaScript)

Credential revocation is not reversable

Document Rails does not provide an API to reverse credential revocation, as both W3C and IETF specifications forbid that.

Accidental revocation may require you to re-issue the credential.

import { revokeCredential } from "@vaultie/document-rails";

await revokeCredential(
    client,
    accessToken,
    organizationId,
    statusListId,
    {
        allocated_idx: parseInt(credential.credentialStatus.statusListIndex)
    }
);

import { suspendCredential } from "@vaultie/document-rails";

await suspendCredential(
    client,
    accessToken,
    organizationId,
    statusListId,
    {
        allocated_idx: parseInt(credential.credentialStatus.statusListIndex)
    }
);

import { unsuspendCredential } from "@vaultie/document-rails";

await unsuspendCredential(
    client,
    accessToken,
    organizationId,
    statusListId,
    {
        allocated_idx: parseInt(credential.credentialStatus.statusListIndex)
    }
);

import { setStatusListValue } from "@vaultie/document-rails";

await setStatusListValue(
    client,
    accessToken,
    organizationId,
    statusListId,
    {
        allocated_idx: parseInt(credential.credentialStatus.statusListIndex),

        // Only values that were present during the initial status list creation request
        // can be utilized here.
        value: 100,
    }
);