Skip to main content

​
API key types

Pilot Status has three kinds of API key. All of them go in the same x-api-key header, and the prefix tells you which kind a key is.
Keys created before 2026-10-28 keep working. They have the older ps_ + hex format, with no kind in the prefix. A legacy number key is still a number key, and a legacy tenant-scoped key is still a workspace key. You do not need to replace them.

​
Number keys

Nothing changed here. Each WhatsApp number has one default key, on the API Keys page, which you regenerate (there is no “create another”). It acts only on its own number: a number key on a workspace-only endpoint gets 403 NUMBER_SCOPE_NOT_ALLOWED. See API keys.

​
Workspace keys

A workspace key is what the docs call a tenant-scoped key: it is bound to the workspace, not to a number. They live on their own screen, Workspace keys (/workspace-api-keys), in the sidebar. Before 2026-10-28 the workspace key was in Profile → API; that tab now holds your account keys. A workspace has two kinds of workspace key:
  • The raw key is shown once, when it is created or regenerated. Store it right away.
  • Your existing tenant-scoped key is the workspace’s primary key.
  • A named key minted by a member is revoked when that member leaves the workspace.
  • Through the API, an account key lists, creates and revokes workspace keys with /v1/workspaces/{id}/api-keys, and rotates the primary key with POST /v1/api-keys/regenerate.

​
Account keys

An account key is yours, not a workspace’s. Any user can create one in Profile → API, up to 20 per user. One key reaches every workspace you are an active member of, and on each request it acts with your current role in the workspace it names: if you are demoted or removed, the key loses that access on the next request. It is the key a reseller uses to create one workspace per end customer and operate all of them with a single credential.

​
Pick the workspace with x-workspace-id

On every endpoint that acts on a workspace, send the workspace id in x-workspace-id. The ids come from GET /v1/workspaces.
  • Inside that workspace, the key behaves like the workspace’s own key, cut down to your role. A role that does not allow the action gets 403 PERMISSION_DENIED.
  • A member limited to some numbers reaches only those numbers, as in the dashboard.
  • x-whatsapp-number-id narrows the request to one number of that workspace, as with a workspace key. An id that is not a number of that workspace gets 404 NUMBER_NOT_FOUND.
  • x-api-key-id is not supported with an account key. Sending both gets 401 API key headers mismatch.
  • Account keys carry a user. Because of that they can do what a workspace key cannot, such as managing members (according to your role), and they can mint workspace keys, which OAuth/MCP tokens cannot.

​
Errors

An account key is the most powerful credential you can hold. It reaches every workspace you belong to, with your role in each. Keep it on your server only, never in a browser or an app, and revoke it in Profile → API if it leaks.

​
Which key to use

  • You send messages from one number: a number key.
  • You run one workspace and manage its numbers, lines and billing: a workspace key — a named one per integration.
  • You resell and keep one workspace per customer: an account key to create the workspaces and act in each one with x-workspace-id. See Billing for resellers.