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:

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
projectsProjects, groups, columns, items, updates, item searchCreating, updating, moving and completing items; posting updates
tasksYour tasks (/v1/tasks/mine)Creating personal tasks; updating and completing tasks assigned to you
knowledgePlaybooks, documents, knowledge search, who knowsCreating and changing documents
automationsAutomations, runs and stepsStarting automations that are started by hand
appsApps, collections and Live recordsCreating and updating records
peoplePeople and job roles
kpisKPIs 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 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.