> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication with x-api-key | Pilot Status

> Authenticate with the x-api-key or x-api-key-id header, ps_ key prefix, number-scoped vs tenant-scoped keys, and key rotation.

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

<Warning>
  There is no Bearer-token authentication. Never send `Authorization: Bearer` — always use the `x-api-key` (or `x-api-key-id`) header.
</Warning>

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

<Note>
  The raw API key is shown only once when generated/regenerated. Store it securely.
</Note>

## 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) | Number lifecycle management — `/v1/numbers/*` (create, list, get, delete, connect, status) and `/v1/remote-pairing/*` — plus account resources: `/v1/api-keys` (list + regenerate each number's key), `/v1/branding`, `/v1/subscription/extra-numbers`, `/v1/billing/checkout`, `/v1/webhooks/*`, and `/v1/embed/sessions` (connect). It cannot send messages. | 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 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 in fact the **only** scope that can manage per-number API keys via `POST /v1/api-keys` — a number-scoped key cannot. It simply **cannot send messages**.
* 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**:

```json theme={null}
{
  "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:

```bash theme={null}
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

<CodeGroup>
  ```bash x-api-key theme={null}
  curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
    -H "x-api-key: ps_your_key_here"
  ```

  ```bash x-api-key-id theme={null}
  curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
    -H "x-api-key-id: ck_xxx"
  ```
</CodeGroup>

## 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

<Warning>
  Use API keys only on the **backend** — never expose them in frontend code, mobile apps, or client-side JavaScript.
</Warning>

* Store the key in environment variables / a secret manager.
* Treat the create/regenerate response as sensitive (do not log the full key).