Status lists

Credential status lists are utilized to perform credential revocation after the initial credential issuance.

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.

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

Supported status list kinds:

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

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:

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 status lists that match output credentials will be automatically selected. If all 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:

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.

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"
    }
);

Credential revocation

Any user in your organization can revoke existing credentials.

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

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