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

# API keys

> Create, rotate, and scope API keys for machine-to-machine integrations.

All API key endpoints require an email-verified session. Keys inherit the owner’s permissions unless you scope them down.

## List keys

### GET `/api/api-keys`

* **Auth** – signed-in, email-verified user.
* **Response** – array of key views:

```json theme={null}
[
  {
    "id": "key_123",
    "name": "CI access",
    "accessType": "projects",
    "keyPrefix": "brw_4f8c",
    "createdAt": "2024-05-28T15:23:18.000Z",
    "updatedAt": "2024-05-28T15:23:18.000Z",
    "lastUsedAt": null,
    "projects": [
      { "id": "proj_1", "slug": "marketing-site", "name": "Marketing" }
    ],
    "permissions": null
  }
]
```

`lastUsedAt` updates automatically whenever the key authenticates a request.

## Create a key

### PUT `/api/api-keys`

* **Body**

```json theme={null}
{
  "name": "local-cli",
  "accessType": "projects",
  "projectIds": ["proj_123"]
}
```

Valid `accessType` values:

* `full` – inherits the owner’s permissions. Do not include `projectIds` or `permissions`.

* `projects` – require `projectIds` (IDs or slugs you already have access to).

* `custom` – require `permissions` (permission strings such as `marketing.pipelines.read`).

* **Response**

```json theme={null}
{
  "key": { "...": "same shape as GET" },
  "secret": "brw_live_xxxxx"
}
```

Store `secret` immediately; the API will never return it again.

## Retrieve / update / delete

| Endpoint                    | Body                                                                  | Notes                                                                                                                                                                                                |
| --------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/api-keys/{id}`    | —                                                                     | Returns the same view as the list call.                                                                                                                                                              |
| `PATCH /api/api-keys/{id}`  | Any combination of `name`, `accessType`, `projectIds`, `permissions`. | Switching `accessType` enforces validation (e.g. moving to `projects` requires `projectIds`). When you change scopes, the API automatically replaces the associated project or permission relations. |
| `DELETE /api/api-keys/{id}` | —                                                                     | Responds with `204 No Content`.                                                                                                                                                                      |

## Using keys

* Send the key with every request via `x-api-key` or `Authorization: ApiKey <secret>`. `Authorization: Bearer <secret>` also works when your client library only supports bearer tokens.
* When both a session cookie and an API key are present, Browsary prefers the more privileged identity (session first, then key).
* Keys scoped to specific projects will receive HTTP 400 errors if they call endpoints outside the allowed list.