Manage Status Credentials

In this walkthrough we take a look at how you can create a status credential configuration, list allocated status entries, get a current status value, and update status values in the configured status credential. Please make sure you have created a credential status service as explained here.

For details on status validation, please refer to the credential-status policy section.

Our implementation covers examples for each of the following standards:

Create A Status Credential Configuration

The first step is to create a configuration. However, the creation of a configuration does not yet issue the actual status credential. It's only after the first status entry has been created with a configuration that the status credential based on the configuration is being issued and made available for verifiers and other parties to access.

When defining the configuration, we decide which key will sign the status credential (keyReference or inline key), the DID of the issuer or an X.509 chain (x5c / x5cReferences), and the config of the status itself. The config sets up properties the depending on the status credential standard, e.g.:

  • W3C standards (BitstringStatusList, StatusList2021, RevocationList2020) - purpose of the status, e.g. revocation, the statusSize and more
  • IETF standard (TokenStatusList)

One status credential can host up to 32.000 status list entries.

Link a KMS Service and X.509 Store

Before creating a configuration, attach the KMS service that owns the keyReference you will use as a dependency of the credential status service — regardless of which storage backend (Setup) you chose. If the configuration uses x5cReferences, attach the X.509 Store as well.

CURL

Endpoint: /v1/{target}/credential-status-service-api/dependencies/add | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/dependencies/add' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "dependency": "waltid.tenant1.kms1"
}'

Body

waltid.tenant1.kms1

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service to which to attach the KMS ({organizationID}.{tenantID}.{credentialStatusServiceID}), e.g. waltid.tenant1.status-service1.

Body Parameters

  • Specifies the ID of the KMS or X.509 Store service that should be linked.

To attach an X.509 Store, send the same request with "dependency": "waltid.tenant1.x509-store".

Response Codes

  • 201 - Dependency attached.

In the examples below we create a configuration for a revocation status credential.


CURL
BODY

Endpoint: /v1/{target}/credential-status-service-api/status-credential/create | API Reference

Example Request

BitstringStatusList
StatusList2021
RevocationList2020
TokenStatusList
curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyReference": "waltid.tenant1.kms1.key1",
  "did": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiMW1rQnBEYWZqVk9ONm9XVmlIZGREZXNEYXpKaXk1R0NTYko3VDU4QkJ3cyIsIngiOiJzZ1BiZWRPQjl1WEMtVG54LUVhV1IxRmg1Y25JLUxRLU43NUV1UE8wV2VFIn0",
  "config": {
    "purpose": "revocation",
    "type": "BitstringStatusList",
    "statusSize": 1,
    "statuses": [
      {
        "status": "0x0",
        "message": "unset"
      },
      {
        "status": "0x1",
        "message": "set"
      }
    ]
  }
}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service in which to execute the status credential creation ({organizationID}.{tenantID}.{credentialStatusServiceID}), e.g. waltid.tenant1.status-service1

Response

  • 200 - Credential Status config created successfully.

Create A Status Entry From The Issuer Service

Although we can use the credential status service to create a new status entry, it's quite a cumbersome process. That's why the issuer service was built to directly communicate & use the credential status service. This way when you make a credential issuance request, you can reference a credential status service config + the initial status in the body of the request. The issuer service then makes the same call we just made above to create a new status entry and the result of the call then gets directly embedded into the credential.

Example Issuance Request Body With Status

BitstringStatusList
StatusList2021
RevocationList2020
TokenStatusList

Notice the credentialData represents a W3C VCDM1.1 or VCMD2.0 credential.

Single
Multiple
{
  "issuerKeyId": "waltid.tenant1.kms1.key1",
  "issuerDid": "did:key:z6MkjoRhq1jSNJdLiruSXrFFxagqrztZaXHqHGUTKJbcNywp",
  "authenticationMethod": "PRE_AUTHORIZED",
  "credentialConfigurationId": "UniversityDegree_jwt_vc_json",
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "http://example.gov/credentials/3732",
    "type": [
      "VerifiableCredential",
      "UniversityDegree"
    ],
    "issuer": {
      "id": "did:web:vc.transmute.world"
    },
    "issuanceDate": "2020-03-10T04:24:12.164Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  // STATUS
  "status": {
    "statusCredentialConfig": "waltid.tenant1.credential-status-service1.config1",
    "initialStatus": "0x0"
  },
  //
  "mapping": {
    "id": "<uuid>",
    "issuer": {
      "id": "<issuerDid>"
    },
    "credentialSubject": {
      "id": "<subjectDid>"
    },
    "issuanceDate": "<timestamp>",
    "expirationDate": "<timestamp-in:365d>"
  }
}

To learn about the issuance requests + the other parameters, please go here.

Body Parameters

  • status - Object defining the status service config + initial status
    • statusCredentialConfig: The ID of the status credential config, e.g. waltid.tenant1.credential-status-service1.config1.
    • initialStatus: The string representing the hexadecimal value of the status, e.g. 0x0.

Note! To ensure compatibility with the issued holder credential, the provided status credential configuration and the requested holder credential must reference the same standard. Providing any other status credential reference will cause an error due to incompatibility between the holder and status credential formats.

Click to expand and see an example of how to manually create a status entry

Create A Status Entry

We do not recommend manually creating status entries, as you will not be able to update the status later through our stack.

With our Status Credential configuration we can now create a status entry. With the following call we will allocate an index within the status credential encoded list for a credential we want to issue with status. The response will return a JSON structure representing the status-entry we can use in the VC issuance request.

CURL
BODY
RESPONSE

Endpoint: /v1/{target}/credential-status-service-api/status-credential/status/create | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/status/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "initialStatus": "0x0"
}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service + credential status config ID in which to create a new status list entry. {organizationID}.{tenantID}.{credentialStatusServiceID}.{statusCredentialConfigID}), e.g. waltid.tenant1.status-service1.revocation-config

Check Status List Capacity

Monitor the capacity of your status lists to ensure you don't run out of entries. Each status list can hold up to 32,000 entries.

CURL
RESPONSE

Endpoint: /v1/{target}/credential-status-service-api/status-credential/capacity | API Reference

Example Request

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/capacity' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Path Parameters

  • orgID: Your organization's Base URL.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service + credential status config ID ({organizationID}.{tenantID}.{credentialStatusServiceID}.{statusCredentialConfigID}), e.g. waltid.tenant1.status-service1.revocation-config

List Status Entries

Use the entries endpoint to inspect the allocated indices in a status list. This is useful for audits, for finding entries with a specific status value, and for getting the index you can use with direct status reads or updates.

The endpoint returns allocated entries only. It does not return empty slots from the status list capacity.

CURL
RESPONSE

Endpoint: GET /v1/{target}/credential-status-service-api/status-credential/entries

Example Request

curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/entries?limit=100&offset=0&status=0x1&sort=index-' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Path Parameters

  • orgID: Your organization's Base URL.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service + credential status config ID ({organizationID}.{tenantID}.{credentialStatusServiceID}.{statusCredentialConfigID}), e.g. waltid.tenant1.status-service1.revocation-config

Query Parameters

ParameterRequiredDescription
limitNoMaximum number of entries to return. Defaults to 100; maximum is 1000.
offsetNoNumber of entries to skip. Defaults to 0.
statusNoFilter entries by status value, for example 0x0 or 0x1.
sortNoSort by index. Supported values are index, index+, and index-. Defaults to ascending index order.

Get A Credential Status

Use the get endpoint to inspect the current status value for one allocated entry. Provide exactly one of session or index.

Both lookup modes require the credential-status.get permission on the status configuration. Session lookups also require access to the issuer session.

Use session when the credential was issued through the issuer service and you want the API to resolve the status index from the issuance session. The session id is available:

  • at issuance (by parsing the credential offer URL)
  • during issuance (via callback mechanism)
  • post-issuance by retrieving it from the list of events through the /v1/events/query endpoint.

Use index when you already know the status list index, for example from the holder credential's status entry or from the entries endpoint. This reads that index in the status list directly and does not require an issuance session.

CURL
RESPONSE

Endpoint: GET /v1/{target}/credential-status-service-api/status-credential/status | API Reference

Example Request

By Session
By Index
curl -X 'GET' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/status?session=waltid.tenant1.issuer-service.session1' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service + credential status config ID ({organizationID}.{tenantID}.{credentialStatusServiceID}.{statusCredentialConfigID}), e.g. waltid.tenant1.status-service1.revocation-config

Query Parameters

  • session: String (optional) - The full path of the issuance session corresponding to the credential-offer-url, e.g. waltid.tenant1.issuer-service.session1.
  • index: Number (optional) - The numeric status list index to read directly, e.g. 11597.

Provide exactly one of session or index.

Update A Credential Status

CURL
BODY
RESPONSE

Endpoint: /v1/{target}/credential-status-service-api/status-credential/status/update | API Reference

Example Request

By Session
By Index
curl -X 'PUT' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/credential-status-service-api/status-credential/status/update' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "waltid.tenant1.issuer-service.session1",
  "status": "0x1"
}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + credential status service + credential status config ID in which to create a new status list entry. {organizationID}.{tenantID}.{credentialStatusServiceID}.{statusCredentialConfigID}), e.g. waltid.tenant1.status-service1.revocation-config
Last updated on September 30, 2026
SetupFull API Reference