#Bitstring Status List Credential

In this walkthrough we take a look at how you can create a Bitstring Status List credential configuration and add or update a status list entry in the related Bitstring Status credential. Please make sure you have created a credential status service as explained here.

Our implementation follows the Bitstring Status List v1.0 standard.

#Create A Bistring Status List 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 list 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, the DID of the issuer, and the config of the status itself. The config includes the purpose of the status, e.g. revocation, the statusSize and more.

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

One StatusListCredential can host 32.000 status list entries.

CURL

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

Example Request

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 '{
  "kid": "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

Body

{
  "kid": "waltid.tenant1.kms1.key1",
  "did": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiMW1rQnBEYWZqVk9ONm9XVmlIZGREZXNEYXpKaXk1R0NTYko3VDU4QkJ3cyIsIngiOiJzZ1BiZWRPQjl1WEMtVG54LUVhV1IxRmg1Y25JLUxRLU43NUV1UE8wV2VFIn0",
  "config": {
    "purpose": "revocation",
    "type": "BitstringStatusList",
    "statusSize": 1,
    "statuses": [
      {
        "status": "0x0",
        "message": "unset"
      },
      {
        "status": "0x1",
        "message": "set"
      }
    ]
  }
}

Body Parameters

kid: resourceIdentifier - Specifies a key used for singing the status credential. The key must come from a KMS service that lives under the same tenant as the credential status service.
did: String - Specifies that DID related to the kid.
config: Object - Status credential configuration.
- purpose: String - Describes the type of status e.g. revocation, suspension or any other custom type.
- type: String - Describes the status credential standard. It should be BitstringStatusList.
- statusSize: String - Describes the size of each status entry in bits. The default value is 1, meaning each status is represented by a single bit. If a value greater than 1 is used, it allows for more complex status messages, and the number of possible status messages must equal the number of possible values (e.g., 2^statusSize).
- statuses: Array - An array of objects, each representing a possible status value and its associated message. Each object contains:
  - status: A string representing the hexadecimal value of the status, prefixed with 0x.
  - message: A descriptive string used by developers for debugging purposes, indicating what the status value represents. It is not intended for end-user display.

Response

201 - Credential Status config created successfully.

#Create A Status List Entry

With our revocation Status List Credential configuration we can now create a status list entry. With the following call we will allocate an index within the status credential bitString and returns the corresponding status-entry

CURL

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

Body

{
  "initialStatus": "0x0"
}

Body Parameters

initialStatus: The string representing the hexadecimal value of the status, prefixed with 0x, e.g. 0x0

Response

201 - Status entry created successfully.

{
  "id": "http://localhost:3000/credentials/99914b932bd37a50b983c5e7c90ae93b#11597",
  "type": "BitstringStatusList",
  "statusPurpose": "revocation",
  "statusListIndex": "11597",
  "statusSize": 1,
  "statusListCredential": "http://localhost:3000/credentials/99914b932bd37a50b983c5e7c90ae93b",
  "statusMessage": [
    {
      "status": "0x0",
      "message": "unset"
    },
    {
      "status": "0x1",
      "message": "set"
    }
  ]
}

The returned status-entry object that can be added to the "credentialStatus" property of the holder credential.

Example of a holder credential with Status

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "https://example.com/credentials/23894672394",
  "type": [
    "VerifiableCredential",
    "EmployeeIdCredential"
  ],
  "issuer": "did:example:12345",
  "validFrom": "2024-04-05T14:27:42Z",
  "credentialStatus": [
    {
      "id": "https://example.com/credentials/status/3#94567",
      "type": "BitstringStatusListEntry",
      "statusPurpose": "revocation",
      "statusListIndex": "94567",
      "statusListCredential": "https://example.com/credentials/status/3"
    }
  ],
  "credentialSubject": {
    "id": "did:example:6789",
    "type": "Person",
    "employeeId": "A-123456"
  }
}

#Create A Status List 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 build to directly communicate & use the credential status service. This way when you make an W3C 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

{
  "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>"
  }
}

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, prefixed with 0x, e.g. 0x0.

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

#Update A Credential Status List Entry

CURL

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

Example Request

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 '{
  "index": "11597",
  "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

Body

{
  "index": "11597",
  "status": "0x1"
}

Body Parameters

index: The index of the credential status to update.
status: The string representing the hexadecimal value of the updated status, prefixed with 0x, e.g. 0x1.

Response

200 - Status updated successfully.

{
  "successful": true
}

401 - Invalid authentication

Setup Intro