> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing and Revoking Credentials

> Find credentials Baselayer minted for your organization and revoke one before it expires.

Credentials are short-lived and minted on demand, but Baselayer keeps a record of every credential it mints for your organization. Use these records to answer "was this agent allowed, for whom, and was it revoked?", and to stop a credential before it expires.

Each record is keyed by `credential_id`, returned by the mint. It is the same value as the `jti` inside the credential. Sites that log the `jti` of credentials they accept can hand it to you in a dispute, and you can look it up here.

## Find a credential

List the credentials your organization minted, newest first. The list never includes the credential itself.

To find active credentials for a person, filter by `individual_ref` and `state=ACTIVE`:

```http theme={null}
GET /issuance/credentials?individual_ref={individual_ref}&state=ACTIVE
```

See every filter in the [API Reference](https://docs.baselayer.com/api-reference/credentials/list-your-organizations-credential-records.md).

To read one record:

```http theme={null}
GET /issuance/credentials/{credential_id}
```

See the [API reference](https://docs.baselayer.com/api-reference/credentials/resolve-one-credential-record-by-its-credential_id.md).

If your API key is allowed to mint credentials, the response also includes `credential`: the credential string the mint returned. It is stored encrypted, and it is bound to the agent's key, so it cannot be presented without the agent's private key.

A `credential_id` your organization did not issue returns `404`, the same as one that does not exist.

## Read the credential record

| Field | Why it matters |
| - | - |
| `credential_id` | The credential to look up or revoke. It matches `jti`. |
| `state` | `ACTIVE`, `EXPIRED` or `REVOKED`, as of the request. |
| `individual_ref`, `business_ref` | Who it represents. |
| `audience` | Which site it was minted for. |
| `issued_at`, `expires_at` | Its lifetime. |
| `disclosed_fields` | What it shared. |
| `active_keys` | The verification checks it attests. |
| `revoked_at`, `revocation_reason`, `revoked_by` | When, why and by whom it was revoked. Null while valid. |

See every record field in the [API Reference](https://docs.baselayer.com/api-reference/credentials/resolve-one-credential-record-by-its-credential_id.md).

## List issuances and revocations

To see every issuance and revocation of your organization's credentials as one stream, newest first by default:

```http theme={null}
GET /issuance/credentials/events
```

See the [API reference](https://docs.baselayer.com/api-reference/credentials/list-your-organizations-credential-events.md).

Filter with `event_type` (`ISSUED` or `REVOKED`, repeat it for both) and a date range. `GET /issuance/credentials/events/export` returns every event the same filters match as a CSV file. See the [API reference](https://docs.baselayer.com/api-reference/credentials/export-your-organizations-credential-events.md).

## Revoke it

```http theme={null}
POST /issuance/credentials/{credential_id}/revoke
```

```json theme={null}
{ "reason": "agent_key_compromise" }
```

See the [API reference](https://docs.baselayer.com/api-reference/credentials/revoke-one-credential.md).

| `reason` | Use it when |
| - | - |
| `agent_key_compromise` | The agent's private key may have leaked. |
| `identity_superseded` | The person's or business's details changed. |
| `identity_withdrawn` | The person or business withdrew. |
| `operator_link_revoked` | The person may no longer act for the business. |
| `fraud_suspected` | You suspect fraud. |

A credential Baselayer revoked shows the reason `administrative_action`. The response is the updated record, with `status: REVOKED`.

### Revocation rules

* It stops this one credential. The person or business can still be minted a new one right away.
* It deletes nothing. The record stays readable with its reason, time and who revoked it.
* It is idempotent. Revoking an already revoked credential changes nothing and keeps the first reason and revoker.
* It cannot be undone. Mint a new credential instead.

Rejecting an operator link does not revoke anything. It blocks new business credentials for that person and business. To stop credentials already minted for the pair, revoke them with `operator_link_revoked`. See [Who Can Act for a Business](https://docs.baselayer.com/docs/kya-who-can-act-for-a-business.md).

## What the site sees

Revoking sets the credential's bit on a status list that Baselayer publishes and signs. Sites check that list on every presentation, and may keep their copy until the list's own refresh time, so sites see the revocation in near-real time. A revoked credential is refused as `CREDENTIAL_REVOKED`.

The list is shared by many credentials, so fetching it doesn't identify which credential or person a site is checking. The list lives at:

```text theme={null}
https://registry.baselayer.com/statuslists/{list_id}
```

Sandbox credentials use `https://sandbox.registry.baselayer.com`. See the [Credential Format Reference](https://docs.baselayer.com/docs/credential-format-reference.md) for how to read it.

## Troubleshooting

| Problem | Fix |
| - | - |
| `404` on lookup or revoke | The `credential_id` is not from your organization, or is from your other environment (sandbox or production). |
| `422` with code `6304` on the list | The `audience` filter is not a valid audience. Use a bare domain or an https address with no path. |
| A revoked credential still worked briefly | Sites may use a cached status list until its refresh time. |
| The list shows `status: VALID` for an old credential | `status` only tracks revocation. Filter with `state=EXPIRED` to find expired ones. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.