API key types

Understand the difference between organization API keys and personal API keys, and which one to use.

Pivot has two kinds of API key. They differ in who the request is from, not in how you send them — both go in the Authorization: Bearer header.

Pick based on one question: should this run as a piece of software the organization owns, or as you?

Organization API keys

An organization API key is a headless identity of its own. It is not a person. It has its own entry under Space Settings > Integrations, its own roles, and its own audit trail. It keeps working after whoever created it leaves the company.

Use one for:

• A bot or service your organization runs.
• A backend job posting release notes or syncing records.
• An app you distribute to other Pivot organizations.

Organization admins create and revoke these in the org admin UI, and choose which spaces the integration can reach.

Personal API keys

A personal API key is you. Requests made with it are attributed to your account and carry exactly the access you already have — every space, room, and block you can open in the app, and nothing more. A message it sends looks like a message you sent, because it is.

Use one for:

• A script that works with your own data.
• The Pivot CLI.
• An AI agent you have authorized to act on your behalf.

Create and revoke them yourself under Settings > Personal API keys.

Choosing between them

	Organization key	Personal key
Acts as	The integration	You
Audit log shows	The integration’s name	Your name
Access	Roles you grant per space	Everything you can already reach
Survives you leaving the org	Yes	No
Belongs to	The organization	You
Managed in	Org admin > Integrations	Settings > Personal API keys

If more than one person depends on the automation, use an organization key. A personal key stops working when the account behind it does, which is the correct behavior for a personal tool and a production outage for a shared one.

The /v1/me endpoints

Some endpoints are about the calling person and only accept a personal key:

• GET /v1/me/profile — your profile.
• GET /v1/me/organizations — the organizations you belong to, and your role in each.
• GET /v1/me/integrations — your own API keys.

An organization key resolves to the integration rather than to a person, so these questions have no meaningful answer for one; calling them with an organization key returns 403.

The reverse also holds in one place: SCIM (/scim/v2/...) provisions an organization’s directory and requires an organization key.

Everything else — rooms, messages, spaces, blocks — accepts either kind.

Rotating and revoking

Both kinds can be rotated and revoked. Rotating issues a new key and the previous key stops working immediately. Revoking invalidates the key outright. In both cases the new key is shown once and cannot be retrieved afterwards, so copy it when it appears.