# List API keys

> The api_keys.list operation: GET /api/v1/api_keys in the REST API and the api_keys_list tool in the MCP server.

Lists the API keys you can see, newest first, in the mode of the request. Never returns secrets or hashes:
keys are recognised by `prefix` (their first 12 characters) and `name`.

An organization-level request sees every key of the organization (org, entity and brand keys); an entity
request sees the entity's keys and its brands' keys; a brand request sees only that brand's keys. Filter by
`kind`, `entityId`, `brandId` and `status` (`active`, `expired`, `revoked`). Paginate with `limit` (1–100,
default 10) and `starting_after` (the `next_cursor` of the previous page).

## At a glance

- **REST:** `GET /api/v1/api_keys`
- **MCP tool:** `api_keys_list`
- **Operation ID:** `api_keys.list`
- **Scope:** Organization, or one of its legal entities or brands
- **Permission:** `keys:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `keys:read` scope
- **Since:** M1

## Request

### Query parameters

| Field            | Type                                  | Required | Description |
| ---------------- | ------------------------------------- | -------- | ----------- |
| `limit`          | integer (1 to 100)                    | No       |             |
| `starting_after` | `key_…` ID                            | No       |             |
| `kind`           | one of `org`, `entity`, `brand`       | No       |             |
| `entityId`       | `ent_…` ID                            | No       |             |
| `brandId`        | `brd_…` ID                            | No       |             |
| `status`         | one of `active`, `expired`, `revoked` | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field               | Type                                                                                               | Description |
| ------------------- | -------------------------------------------------------------------------------------------------- | ----------- |
| `object`            | `"list"`                                                                                           |             |
| `data`              | array of object                                                                                    |             |
| `data[].id`         | `key_…` ID                                                                                         |             |
| `data[].object`     | `"api_key"`                                                                                        |             |
| `data[].kind`       | one of `org`, `entity`, `brand`                                                                    |             |
| `data[].livemode`   | boolean                                                                                            |             |
| `data[].name`       | string                                                                                             |             |
| `data[].prefix`     | string                                                                                             |             |
| `data[].scopes`     | array of one of 98 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) |             |
| `data[].status`     | one of `active`, `expired`, `revoked`                                                              |             |
| `data[].orgId`      | `org_…` ID                                                                                         |             |
| `data[].entityId`   | `ent_…` ID or null                                                                                 |             |
| `data[].brandId`    | `brd_…` ID or null                                                                                 |             |
| `data[].createdBy`  | string                                                                                             |             |
| `data[].createdAt`  | date-time                                                                                          |             |
| `data[].updatedAt`  | date-time                                                                                          |             |
| `data[].expiresAt`  | date-time or null                                                                                  |             |
| `data[].lastUsedAt` | date-time or null                                                                                  |             |
| `data[].revokedAt`  | date-time or null                                                                                  |             |
| `has_more`          | boolean                                                                                            |             |
| `next_cursor`       | `key_…` ID or null                                                                                 |             |

## Examples

### Active keys of a brand

```http
GET /api/v1/api_keys?brandId=brd_01m4ttwd3veh9apbewxheq5xh5&status=active
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "key_01m4ttwd3tesktp0hc6bpxwkpd",
      "object": "api_key",
      "kind": "brand",
      "livemode": false,
      "name": "Billing backend",
      "prefix": "or_test_acme",
      "scopes": ["customers:write", "subscriptions:write", "usage:write"],
      "status": "active",
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": "2026-10-20T09:30:00.000Z",
      "revokedAt": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Two keys per page

```http
GET /api/v1/api_keys?limit=2
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "key_01m4ttwd3veh9apbewxheq5xh1",
      "object": "api_key",
      "kind": "org",
      "livemode": false,
      "name": "Automation",
      "prefix": "or_test_acme",
      "scopes": ["customers:write", "subscriptions:write", "usage:write"],
      "status": "active",
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "entityId": null,
      "brandId": null,
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": null,
      "revokedAt": null
    },
    {
      "id": "key_01m4ttwd3tesktp0hc6bpxwkpd",
      "object": "api_key",
      "kind": "brand",
      "livemode": false,
      "name": "Billing backend",
      "prefix": "or_test_acme",
      "scopes": ["customers:write", "subscriptions:write", "usage:write"],
      "status": "active",
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
      "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z",
      "expiresAt": null,
      "lastUsedAt": null,
      "revokedAt": null
    }
  ],
  "has_more": true,
  "next_cursor": "key_01m4ttwd3tesktp0hc6bpxwkpd"
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                                | What to do                                                                                                  |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or pagination value is invalid.                            | Fix the fields listed in `details.issues` and send the request again.                                       |
| [`scope_mismatch`](https://ownrecord.io/docs/reference/errors.md#scope_mismatch)       | 403         | A filter names an entity or brand outside the scope of the request. | Use credentials scoped to that organization, entity or brand, or leave the scope fields out of the request. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't see API keys here.                                        | Ask an organization owner or admin for a role or scope that allows this action.                             |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).