Every request carries an API key as a Bearer token:
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.
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
:readscope. - 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 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
403with the codeapi_disabled.
Every change made through the API or MCP is recorded with the key that made it.