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 never carry PlaybookOps staff powers: a platform admin's key works like an org admin's, in their own organization only.
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, completing, archiving and deleting items; posting updates
tasksYour tasks (/v1/tasks/mine)Creating and deleting personal tasks; updating and completing tasks assigned to you
knowledgePlaybooks, folders, documents, document changes, knowledge search, who knowsCreating playbooks, folders and documents; 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 valuesRecording and clearing values for KPIs you own

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

  • Read-only has every :read scope.
  • Full access has everything, including scopes added later.
  • Custom lets you choose, area by area: no access, read, or read and change. A docs agent, for example, only needs knowledge:write, which can't reach projects or tasks.

Give each key the least it needs. If a custom key leaks, it can only reach the areas you picked.

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.