# API keys and scopes

> How keys work, what each scope allows, and how admins stay in control.

Every request carries an API key as a Bearer token:

```http
Authorization: Bearer pbo_live_3f9a1c2b7d4e_…
```

You make keys under Account → API keys in PlaybookOps.

## A key acts as you

A key belongs to the person who made it and works inside their organization. It reaches exactly what they can reach in the app: the projects they're on, the apps they can open, the automations they can see. Changes made with it show up as theirs.

- If the person leaves the organization or is deactivated, their keys stop working.
- Org viewers can read through the API but can't change anything. Project viewers can't change that project.

> **Keys for shared integrations**
> Since a key acts as its owner, make keys for shared agents and integrations from an account whose access matches what they should reach.

## Scopes

Scopes narrow what a key may do. Each is an area and an action:

| Area | `:read` allows | `:write` allows |
| --- | --- | --- |
| `projects` | Projects, groups, columns, items, updates, item search | Creating, updating, moving and completing items; posting updates |
| `tasks` | Your tasks (`/v1/tasks/mine`) | Creating personal tasks; updating and completing tasks assigned to you |
| `knowledge` | Playbooks, documents, knowledge search, who knows | Creating and changing documents |
| `automations` | Automations, runs and steps | Starting automations that are started by hand |
| `apps` | Apps, collections and Live records | Creating and updating records |
| `people` | People and job roles | |
| `kpis` | KPIs and their values | |

A `:write` scope includes `:read` for the same area. When you make a key, you pick one of two levels:

- **Read-only** has every `:read` scope.
- **Full access** has everything, including scopes added later.

A request outside the key's scopes gets `403` with the code `missing_scope`. Over MCP, an agent only sees the tools its key's scopes allow. Each endpoint in the [API reference](https://developers.playbookops.ai/reference) shows the scope it needs.

## Keeping keys safe

- **Keys are shown once.** PlaybookOps keeps only a hash, so a lost key can't be recovered. Make a new one.
- **Set an expiry.** Keys can expire after 30, 90 or 365 days, or never. Pick the shortest that works.
- **Revoke keys you're done with** from Account → API keys. A revoked key stops working within 30 seconds.
- **Each person can have up to 25 active keys.**
- **Keep keys on servers.** Never put a key in code that runs in a browser or a mobile app, where anyone can read it.

## For admins

Org admins manage the API under **Admin → API** in PlaybookOps:

- **Usage** shows the organization's API and MCP traffic: calls over time, failures, response times and AI credits, broken down by key and by action, with recent failures and why they failed.
- **Keys** lists every key in the organization with its owner and when it was last used. Admins can revoke any of them.
- **The API switch** turns the API and MCP off for the whole organization. While it's off, every key gets `403` with the code `api_disabled`.

Every change made through the API or MCP is recorded with the key that made it.
