Skip to main content
Every /v1 request authenticates with a project API key, sent as a bearer token:
There’s no separate login step and no session. Send the header on every call.
Keys minted against production start with pk_live_; keys minted in a non-production environment start with pk_test_. They behave identically — the prefix just tells you at a glance which environment a key came from, which is worth checking first when a key 401s.

​
Create a key

Keys live under Settings → API → API Keys.
The API section is for owners and admins. If you’re a workspace member without admin access, it doesn’t appear in your Settings sidebar at all.
1

Open Settings → API

Pick the project you want the key to act on. A key belongs to that one project.
2

Click New key

Give it a name you’ll recognise later — “Zapier integration”, “order webhook worker”. The name is for you; it’s never sent anywhere.
3

Tick only the scopes it needs

Grant the minimum. A key that only sends messages should hold messages:send and nothing else. See Scopes.
4

Copy the key immediately

The secret is shown once, in a dialog, with a copy button. Paige stores only a hash of it — nobody, including Paige support, can show it to you again.
Never put a key in front-end code, a mobile app, or a public repository. Anyone holding it can do everything its scopes allow to your project — including sending WhatsApp messages to your customers. Store it as a server-side secret, for example in an environment variable like PAIGE_API_KEY.

​
Rotate and revoke

Each key row has Rotate and Revoke, plus an option to edit its scopes.
  • Rotate issues a fresh secret for the same key and shows it once. Update your integration promptly — the old secret stops working.
  • Revoke deletes it. Anything still using it starts getting 401 invalid_api_key immediately.
Rotate when a key may have leaked, when someone with access leaves, or just periodically. Editing scopes takes effect straight away — no new key needed.

​
The key is also the project

There is no project id in any /v1 path. The key resolves to its project on every request, which is why /v1/messages needs no more context than the message itself. Confirm which project a key resolves to, and what it may do there, with GET /v1/ping.
A key stops working while its project is paused or deleted — you’ll get 403 project_inactive. Pausing is a billing state, so if an integration suddenly 403s across the board, check the project’s subscription before you go hunting through your code.

​
Signing in instead of pasting a key

There’s a second way in, for AI agents: Paige’s MCP server supports OAuth, so clients like Claude and ChatGPT let you click Connect, sign in to Paige, and approve on a consent screen. No raw key is ever pasted, and access is revocable from Settings → API → Connected agents. An OAuth connection issues an access token (it starts with mcp_at_) that works as a bearer against the same /v1 endpoints. The differences worth knowing:
  • One connection can reach several projects, each with its own scopes. Permissions never pool — a project can’t borrow a scope from a sibling project on the same connection.
  • Tokens are revocable and can expire. A revoked or expired one returns 401 invalid_token.
Full walkthrough: Connect an AI agent.

​
Targeting a project with X-Paige-Project

Because an OAuth connection can cover several projects, requests can name one:
Get valid ids from GET /v1/projects, which lists every project the credential may act on along with its per-project scopes and which one is the default. Matching is case-insensitive. Scopes are always checked against the selected project only.
A plain pk_live_… key covering one project never needs this header. Skip it unless you’re building against a multi-project OAuth connection.

​
Authentication errors