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

# Authentication

> API key formats, headers, and the gateway auth contract.

All endpoints except `/public/*` require a valid API key. WXA VPN Intelligence
uses a two-path auth model — the gateway validates the customer key and the
backend trusts what the gateway forwards.

## API key format

Customer API keys follow the pattern:

```
wxa_vpn_<key-id>_<key-secret>
```

Keys are issued per user and rate-limited per tier. The secret portion is
shown exactly once at key generation and bcrypt-hashed at rest.

## How to authenticate

### Option A — Authorization header (recommended)

```
Authorization: Bearer wxa_vpn_<key-id>_<key-secret>
```

The wxaintel-platform gateway (or the NAF BFF on
`vpn-proxy-detection.whoisxmlapi.com`) validates the key, then forwards the
request to the backend with two internal headers:

* `X-Internal-Key` — shared secret that proves the request came from a
  trusted gateway (not a direct backend bypass)
* `X-Tier` — the customer's plan tier (`free` | `starter` | `pro` | `scale` |
  `business` | `enterprise`)

The backend does **not** process the raw customer key — it only trusts
`X-Internal-Key` + `X-Tier` from the gateway.

### Option B — NAF query-param path

When the NAF endpoint is configured (`NAF_ENDPOINT` + `NAF_API_ID=92`), the
BFF accepts the key as a query parameter:

```
GET /api/v1/vpn/ip/1.2.3.4?apiKey=wxa_vpn_<key-id>_<key-secret>
```

NAF calls `validate_call` to gate on subscription/credits, then
`log_successfull_call.php` to deduct credits (N = IP count on `/ip/batch`).
The feature tier comes from the backend's own `api_keys` mapping. When
`NAF_ENDPOINT` is not set, the `?apiKey=` parameter is inert and Option A is
the only valid auth.

## Tiers and rate limits

Rate limits are enforced per key. See [tiers](/tiers) for the full feature matrix.

| Tier       | Monthly quota | Rate limit     |
| ---------- | ------------- | -------------- |
| Free       | 10,000        | 2 req/min      |
| Starter    | 1,000,000     | 30 req/min     |
| Pro        | 10,000,000    | 100 req/min    |
| Scale      | 50,000,000    | 250 req/min    |
| Business   | Unlimited     | 500 req/min    |
| Enterprise | Unlimited     | 10,000 req/min |

Exceeding the rate limit returns `HTTP 429` with a `Retry-After` header
indicating seconds until the next window. See
[error handling](/guides/error-handling).

## Rotation

Rotate keys at least every 90 days, or immediately if you suspect leakage:

1. **Generate a new key** in the dashboard
2. **Deploy the new key** to your applications
3. **Revoke the old key** once traffic has migrated (30-second propagation)

Both keys remain valid during overlap — there's no forced cutover window.

## Multiple environments

Generate one key per environment (`prod`, `staging`, `ci`) and tag them in
the dashboard so usage analytics break down cleanly. Keys are not
environment-locked at the API layer; the tagging is for your own audit.

## What not to do

* **Don't commit keys to source control.** Use environment variables, a
  secrets manager, or `.env` files added to `.gitignore`.
* **Don't share keys across teams.** Generate one key per team or service.
* **Don't bypass per-key rate limits by issuing many keys.** Distributed
  request patterns intended to evade quotas violate the
  [Acceptable Use Policy](https://github.com/whois-api-llc/wxa_vpn/blob/main/docs/legal/acceptable-use-policy.md).

## Public no-auth endpoints

A subset of endpoints under `/public/*` is available without an API key,
with aggressive per-IP rate limits and a restricted response shape. These
exist for evaluation and self-checks — not production traffic.