porchopsdev
DocsAPI tokens
MCP · BYOA

API tokens

A PorchOps API token is a bearer credential scoped to one workspace and a set of permissions. It authenticates every MCP call your agent makes.

The token format

Tokens carry the pkk_ family prefix, then a short workspace slug, then 160 bits of random body. The slug makes a token self-identifying in your own logs without a lookup.

token shape
pkk_alphacorp_K7H2Q8M4N9P0RST5VWXY1J6Z3CABDFGE

PorchOps stores only a hash of the token, never the token itself. The full value is shown once, at creation, and is unrecoverable afterward. A leaked database leaks hashes, not usable tokens.

Creating a token

Create tokens in Settings → API keys. The create dialog asks for a name, an app scope (the whole workspace or one app), a set of permissions, and an expiry. On submit, PorchOps shows the full token once. Copy it before you close the dialog.

Permission scopes

A token grants only the permissions you check at creation. The default is the minimal read bundle (customer.read, knowledge_base.read, metrics.read, code_context.read). Permissions are checked at the MCP middleware before any tool runs; a token with customer.read that calls a write tool gets a 403.

Read scopes
  • customer.readRead the Customer Graph (lookup, search, timeline, summary).
  • agent.runs.readRead run history; required alongside customer.read for customer.related_runs.
  • knowledge_base.readRead knowledge-base items (v1.5 server).
  • metrics.readRead aggregate business metrics (v1.5 server).
  • code_context.readRead changelog, ship log, and status state (v1.5 server).
  • agent.readRead agent list and personality settings (v1.5 server).
  • approval.readRead the approval queue (v1.5 server).
  • playbook.readList and inspect playbooks (v1.5 server).

Write scopes are never granted by default. They land with the v1.5 write tools; a token must opt into each one explicitly.

Write scopes (v1.5)
  • customer.writeUpdate customers and write customer memory (v1.5).
  • knowledge_base.writeCreate and update knowledge-base items (v1.5).
  • approval.writeApprove or reject from an external client (v1.5).
  • playbook.runTrigger a playbook run (Growth+, Scale, and Enterprise, v1.5).

Per-tier token caps

The number of active tokens a workspace can hold depends on its tier. Revoking a token frees a slot immediately.

Active token cap by tier
  • Free0: creation is refused; the endpoints return 403.
  • Growth3 active tokens
  • Growth+10 active tokens
  • Scale50 active tokens
  • Enterpriseunlimited

Rotation

Rotate a token to replace it without downtime. Rotation mints a new token with the same name, scope, and permissions, and schedules the old one to auto-revoke after a 7-day grace window. During the window both tokens work: update your client to the new token, confirm it works, and the old one retires on its own. If something breaks, cancel the rotation before the window closes and the old token reverts to active. Canceling only reverts the old token: the replacement stays active until you revoke it separately.

Expiry and revocation

  • Expiry: a token stops authenticating the moment it passes its expires_at. Set it at creation (30d / 90d / 1y / none).
  • Revocation: revoke a token any time from the API keys page. Revocation is immediate. The row stays visible under a Revoked tab for 30 days so you can see what was revoked and when, then it archives.
  • Downgrade to Free: if a workspace downgrades to Free, its tokens are revoked automatically (BYOA is paid-only).

Every token lifecycle event (created, revoked, rotated) and every tool call a token makes appears in your workspace audit log.