# Credential Status Lists

Credential status management allows issuers to track and update the revocation and suspension status of issued W3C credentials. The Cloud Agent uses [Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/) to efficiently manage credential statuses.

### Create a Status List Definition

A status list definition must be created before credentials can be assigned to status lists. The definition specifies which purposes (revocation and/or suspension) the status lists will support and which issuer [DID](https://docs.sudoplatform.com/guides/decentralized-identity/cloud-agent/cloud-agent-admin-api/dids) will manage them. A status list should be created with a unique identifier chosen by the API consumer.

```graphql
mutation MyMutation {
  createStatusListDefinition(
    input: {
      identifier: "my-status-list-def"
      purposes: [REVOCATION, SUSPENSION]
      issuerDid: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
    }
  ) {
    identifier
    purposes
    issuerDid
    lists {
      listNumber
      purpose
    }
    createdTimestamp
  }
}
```

### Manually Assign a Credential to Status Lists

Before issuing a credential, assign it to status lists to enable revocation and suspension tracking. This returns [W3C credential status entry objects](https://www.w3.org/TR/vc-bitstring-status-list/#bitstringstatuslistentry) that should be embedded in the credential before issuing.

{% hint style="info" %}
Alternatively this credential assignment to a status list can be handled automatically when issuing credential: [#embed-credential-status](https://docs.sudoplatform.com/guides/decentralized-identity/cloud-agent/cloud-agent-admin-api/standalone-vc-issuance#embed-credential-status "mention").
{% endhint %}

```graphql
mutation MyMutation {
  assignCredentialToStatusList(
    input: {
      newEntry: {
        credentialId: "urn:uuid:12345678-1234-1234-1234-123456789abc"
        statusListDefinitionIdentifier: "my-status-list-def"
      }
    }
  ) {
    w3cCredentialStatusJsons
  }
}
```

### Update Credential Statuses

Update the revocation and/or suspension status of one or more credentials. The `publishImmediately` flag determines whether the status lists are published automatically after the update. The updated status will not be available publicly until it is published.

```graphql
mutation MyMutation {
  updateCredentialStatuses(
    input: {
      updates: [
        {
          entry: {
            credentialId: "urn:uuid:12345678-1234-1234-1234-123456789abc"
            statusListDefinitionIdentifier: "my-status-list-def"
          }
          revoked: true
          suspended: false
        }
      ]
      publishImmediately: true
    }
  ) {
    success {
      credentialId
      statusListDefinitionIdentifier
    }
    failed {
      entry {
        credentialId
        statusListDefinitionIdentifier
      }
      error
    }
  }
}
```

### Publish Status Lists

Publish status lists to make credential status updates publicly available. This operation publishes all status lists associated with a status list definition.

```graphql
mutation MyMutation {
  publishStatusList(
    input: {
      identifier: "my-status-list-def"
    }
  ) {
    success {
      listNumber
      purpose
    }
    failed {
      list {
        listNumber
        purpose
      }
      error
    }
  }
}
```

### View Status List Definitions

View all status list definitions managed by the agent.

```graphql
query MyQuery {
  statusListDefinitions {
    items {
      identifier
      purposes
      issuerDid
      lists {
        listNumber
        purpose
      }
      createdTimestamp
    }
  }
}
```

Alternatively, view a single status list definition by its unique identifier.

```graphql
query MyQuery {
  statusListDefinition(
    identifier: "my-status-list-def"
  ) {
    identifier
    purposes
    issuerDid
    lists {
      listNumber
      purpose
    }
    createdTimestamp
  }
}
```

### Check Credential Statuses

Check the current revocation and suspension status of one or more credentials. This returns the internally recorded status entries, the external public status may not match if the changes have not been published.

```graphql
query MyQuery {
  credentialStatuses(
    input: {
      entries: [
        {
          credentialId: "urn:uuid:12345678-1234-1234-1234-123456789abc"
          statusListDefinitionIdentifier: "my-status-list-def"
        }
      ]
    }
  ) {
    statuses {
      entry {
        credentialId
        statusListDefinitionIdentifier
      }
      revoked
      suspended
    }
  }
}
```
