Scopes & Token Types

Project Feed API keys come in two scopes: workspace-bound (today's default) and account-bound (new). The scope determines which resources a key can touch and which API surfaces it can call.

Workspace-scoped keys

Created from a workspace's developer settings (/{workspaceSlug}/settings/developers). The key is bound to exactly one workspace; every /api/v1/* request implicitly operates on that workspace. Membership and IP-allowlist policies are re-checked on every request.

Use this for: integrations and automation owned by the workspace (CI bots, internal services, partner integrations). When the creating user leaves the workspace, the workspace admin keeps the key. Survives staff turnover.

Free workspace keys may only request projects:read, posts:read, comments:read, reactions:read, and tasks:read. Write scopes, members, media, notifications, audit logs, webhooks, docs, canvas, profile, and API token listing require Pro service accounts.

Account-scoped keys (personal access tokens)

Created from your account settings (/account/settings/api-keys). The key authenticates as you, independent of any workspace. By default it can only call the identity-side /api/v1/me/* surface. To grant access to workspace resources, select an audience workspace list at creation — the key can then reach those workspaces (subject to per-workspace policy).

Use this for: personal CLI tools, scripts, and integrations that follow you across workspaces. Required to have an expiration date (default 90 days, maximum 365 days).

Permission strings

Permissions follow a resource:action convention. A :write permission implies :read on the same resource.

Account-scope keys can request:

profile:read · profile:write — read or update your profile, list memberships, see your push subscriptions
api-keys:read — list your own personal access tokens
Workspace resource scopes such as posts:read, tasks:write, or docs:read when the key has an explicit workspace audience and that workspace allows the scope

Workspace-scope keys can additionally request:

projects:*, posts:*, comments:*, reactions:*, tasks:*, media:*, webhooks:*, docs:*, and canvas:* — workspace content
members:read — workspace member directory
audit-logs:read — audit log export (Pro Plus, owner/admin only)

Selecting a workspace from an account-scope key

When a key has multiple workspaces in its audience, the request picks the target via:

X-Organization-Id: <orgId> request header
?organizationId=<orgId> query parameter
Implicit from the resource id when the path resolves to a single workspace (e.g. GET /api/v1/posts/{id} resolves org from the post)

Each request runs through four enforcement layers: IP allowlist,allowAccountScopedKeys workspace opt-out, apiKeyAllowedScopes workspace scope filter, and apiKeyMaxAge workspace rotation policy.

Token format

New tokens are issued in the form pf_<env>_<random36>_<crc6> (49 chars total). <env> is p (production), s (staging), or t (test) so a leaked key can be triaged in seconds. The CRC suffix lets secret scanners validate format offline. Legacy pf_live_* keys continue to work until rotated.