Skip to main content

​
API Authentication

Every request to the Pilot Status API requires an API key in one of these headers:
  • x-api-key: the raw key (ps_*)
  • x-api-key-id: the API key ID (the backend resolves it internally)
There is no Bearer-token authentication. Never send Authorization: Bearer — always use the x-api-key (or x-api-key-id) header.

​
Key prefix

All raw keys use the ps_ prefix.

​
Where to find an API key

  • Number-scoped key: dashboard /api-keys — each WhatsApp number has one default key that you can Regenerate (there are no sub-keys / no parent-child).
  • Tenant-scoped key: dashboard Profile → API tab — a singleton you generate/regenerate.
The raw API key is shown only once when generated/regenerated. Store it securely.

​
Key scope (number vs tenant)

Every API key has a scope that determines which endpoints it can call. Both scopes authenticate the same way (x-api-key: ps_* or x-api-key-id).
ScopeBound toCan callWhere to find it
Number-scoped (default)One WhatsApp numberAll action/data endpoints for that number — POST /v1/messages/send, message status, cancel, groups, newsletters, templates, analytics, mediaDashboard → API Keys page (one default key per number; Regenerate)
Tenant-scoped (singleton)The tenant (no number)Only number lifecycle management: /v1/numbers/* (create, list, get, delete, connect, status) and /v1/remote-pairing/*Dashboard → Profile → API tab

​
Number-scoped key

The default key type. It is linked to a single WhatsApp number and is used for all of that number’s action and data operations (sending messages, status lookups, groups, newsletters, templates, analytics, media). It tracks every action performed for that number.

​
Tenant-scoped key

A tenant-scoped key is a singleton per tenant with no associated number. It is intended for SaaS platforms that connect and manage multiple numbers (including their customers’ numbers) via the public API.
  • It can call only the endpoints under /v1/numbers/* and /v1/remote-pairing/*.
  • It cannot send messages and cannot issue other API keys.
  • It is generated/regenerated in the dashboard under Profile → API tab.
If a tenant-scoped key is used on a per-number action/data endpoint (e.g. POST /v1/messages/send), the API responds with HTTP 403: 
{
  "error": "This endpoint requires a number-scoped API key",
  "code": "TENANT_SCOPE_NOT_ALLOWED"
}

​
Regenerate / rotate keys

Regenerate a number’s default key from the dashboard API Keys page, or via the API: 
curl -X POST "https://pilotstatus.com.br/v1/api-keys/regenerate" \
  -H "x-api-key: ps_your_current_key"
Regenerating invalidates the previous key immediately; the new raw key is returned only once.

​
Example requests

curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key: ps_your_key_here"

​
Common errors

  • 401 — missing or invalid x-api-key / x-api-key-id header.
  • 403 — valid key, but operation blocked (e.g., a tenant-scoped key calling a per-number action endpoint → code: "TENANT_SCOPE_NOT_ALLOWED", or a number-scoped key calling a tenant-only endpoint → code: "NUMBER_SCOPE_NOT_ALLOWED").

​
Security best practices

Use API keys only on the backend — never expose them in frontend code, mobile apps, or client-side JavaScript.
  • Store the key in environment variables / a secret manager.
  • Treat the create/regenerate response as sensitive (do not log the full key).