> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hooper.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, environments, and rate limits.

Every request needs an API key in the `Authorization` header:

```bash theme={null}
curl https://api.hooper.gg/v1/balance \
  -H "Authorization: Bearer hk_prod_8KzQ…"
```

Keys are issued by Hooper for your organization. The plaintext is shown once when it's created; Hooper stores only a hash and cannot recover it. Keep it server-side — never ship it in a browser or mobile app.

## Key format

| Prefix                     | Meaning                                            |
| -------------------------- | -------------------------------------------------- |
| `hk_prod_…`                | API key for production (`api.hooper.gg`)           |
| `hk_stg_…`                 | API key for staging                                |
| `hws_prod_…` / `hws_stg_…` | Webhook signing secret (see [Webhooks](/webhooks)) |

The middle segment names the environment that issued the credential. A production server refuses a staging key with a specific error so the mismatch is obvious:

```json theme={null}
{ "error": { "type": "authentication_error", "code": "wrong_environment",
             "message": "This key was minted for the 'stg' environment; this server accepts 'prod' keys" } }
```

## Error codes

| HTTP | `code`                | Meaning                                                         |
| ---- | --------------------- | --------------------------------------------------------------- |
| 401  | `missing_api_key`     | No `Authorization: Bearer` header                               |
| 401  | `invalid_api_key`     | Malformed, unknown, or revoked key                              |
| 401  | `wrong_environment`   | Key belongs to the other environment                            |
| 429  | `rate_limit_exceeded` | More than 60 requests/minute on this key — honour `Retry-After` |

## Rotating a key

Ask Hooper to mint a new key, switch your integration to it, then have the old one revoked. Revocation is immediate; a revoked key returns `invalid_api_key`.