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).

Scope	Bound to	Can call	Where to find it
Number-scoped (default)	One WhatsApp number	All action/data endpoints for that number — `POST /v1/messages/send`, message status, cancel, groups, newsletters, templates, analytics, media	Dashboard → API Keys page (one default key per number; Regenerate)
Tenant-scoped (singleton)	The tenant (no number)	Everything. Number lifecycle — `/v1/numbers/` and `/v1/remote-pairing/` — account resources (`/v1/api-keys`, `/v1/branding`, `/v1/subscription/extra-numbers`, `/v1/billing/checkout`, `/v1/webhooks/`, `/v1/embed/sessions`), and* every per-number endpoint of any number in the tenant by naming it in `x-whatsapp-number-id`.	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.

Tenant API key — Profile → API — the tenant-scoped key (manages numbers and acts on any of them via the public API).

It manages numbers via /v1/numbers/* and /v1/remote-pairing/*, and manages account resources: /v1/api-keys (list every number’s key and regenerate it), /v1/branding, /v1/subscription/extra-numbers, /v1/billing/checkout, /v1/webhooks/*, and /v1/embed/sessions (connect).
It is the only scope that can manage per-number API keys via POST /v1/api-keys — a number-scoped key cannot.
It can call any per-number endpoint — sending included — by naming the number in the x-whatsapp-number-id header. You do not need a separate key per number.
It is generated/regenerated in the dashboard under Profile → API tab.

Acting on a specific number with a tenant key

Send x-whatsapp-number-id with the id of the number to act as. It accepts either the WhatsAppNumber.id or the primary WhatsAppInstance.id returned by GET /v1/numbers.

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_tenant_key" \
  -H "x-whatsapp-number-id: <id from GET /v1/numbers>" \
  -H "Content-Type: application/json" \
  -d '{"destinationNumber":"5511999999999","text":"Hi"}'

Omit the header on a per-number endpoint and the API responds with HTTP 403, telling you to name the number:

{
  "error": "This endpoint acts on a single WhatsApp number: send the x-whatsapp-number-id header naming the number to act on (its id or instance id from GET /v1/numbers) | Este endpoint atua sobre um único número de WhatsApp: envie o header x-whatsapp-number-id indicando o número desejado (o id dele ou o id da instância, obtidos em GET /v1/numbers)",
  "code": "TENANT_SCOPE_NOT_ALLOWED"
}

An id that does not belong to your tenant is rejected with HTTP 404 — a tenant key can never reach another tenant’s number. Body: {"error":"x-whatsapp-number-id does not name a WhatsApp number of this account | …","code":"NUMBER_NOT_FOUND"}.

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"

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

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).

Overview

Messaging

Templates

Numbers

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

API Authentication with x-api-key | Pilot Status

API Authentication

Key prefix

Where to find an API key

Key scope (number vs tenant)

Number-scoped key

Tenant-scoped key

Acting on a specific number with a tenant key

Regenerate / rotate keys

Example requests

Common errors

Security best practices

​API Authentication

​Key prefix

​Where to find an API key

​Key scope (number vs tenant)

​Number-scoped key

​Tenant-scoped key

​Acting on a specific number with a tenant key

​Regenerate / rotate keys

​Example requests

​Common errors

​Security best practices

API Authentication

Key prefix

Where to find an API key

Key scope (number vs tenant)

Number-scoped key

Tenant-scoped key

Acting on a specific number with a tenant key

Regenerate / rotate keys

Example requests

Common errors

Security best practices