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

# API keys

> List, create, and revoke API keys through the REST API.

API-key routes require an admin-capable key.

A personal access token can manage keys for an explicit project through
`/projects/{project_id}/api-keys`. Its effective permission for that project
must be `admin`. The top-level `/api-keys` aliases remain useful for project
keys and for a PAT when project selection is unambiguous.

## API key resource

```json theme={null}
{
  "id": "key_abc123",
  "name": "reporting job",
  "prefix": "bsk_live_xxxxxxxx",
  "created_at": "2026-06-28T10:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null
}
```

The raw token is only returned by `POST /api-keys`.

## List API keys

```http theme={null}
GET /api/v1/api-keys
Authorization: Bearer <api_key>
```

Query parameters:

| Query    | Description                                 |
| -------- | ------------------------------------------- |
| `limit`  | Page size. Defaults to `50`, maximum `200`. |
| `cursor` | Pagination cursor.                          |

Response:

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "reporting job",
      "prefix": "bsk_live_xxxxxxxx",
      "created_at": "2026-06-28T10:00:00.000Z",
      "last_used_at": null,
      "revoked_at": null
    }
  ],
  "meta": { "next_cursor": null }
}
```

## Create API key

```http theme={null}
POST /api/v1/api-keys
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: create-key-001
```

Request:

```json theme={null}
{ "name": "reporting job" }
```

Response status is `201`.

```json theme={null}
{
  "id": "key_abc123",
  "name": "reporting job",
  "prefix": "bsk_live_xxxxxxxx",
  "masked_value": "bsk_live_xxxxxxxx******abcd",
  "token": "bsk_live_...",
  "created_at": "2026-06-28T10:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null
}
```

Store `token` immediately. It is not returned again.

For CI automation with a PAT, create a project key directly:

```http theme={null}
POST /api/v1/projects/prj_abc123/api-keys
Authorization: Bearer <personal_token>
Content-Type: application/json

{ "name": "deploy pipeline" }
```

## Revoke API key

```http theme={null}
DELETE /api/v1/api-keys/{key_id}
Authorization: Bearer <api_key>
Idempotency-Key: revoke-key-001
```

`key_id` may include the `key_` prefix. The response is the revoked API-key
resource with `revoked_at` set.