# Authentication

All API requests must be authenticated with a Bearer API key.

Source: https://ayewatch.ai/documentation/authentication

## Generating API Keys

API keys are available on paid plans. Generate and manage your keys in the [Developer dashboard](https://ayewatch.ai/developer).
You can create up to the limit for your plan and revoke them at any time.

> **Plan requirement:** API keys are only available on paid plans. Upgrade your plan to enable API
> access.

## Rate Limits

Each API key is limited to 120 requests per minute by default. Every authenticated response includes
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `X-Request-Id` headers. A 429
response also includes `Retry-After`.

## Key Format

All AyeWatch API keys follow this format:

```text
aw_live_<96 hex characters>
```

Example: `aw_live_a1b2c3d4e5f6...` (total length: ~104 characters)

## Making Authenticated Requests

Pass your API key in the `Authorization` header as a Bearer token:

```bash
curl https://ayewatch.ai/api/v1/topics \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"
```

## Security Tips

- **Never expose keys client-side.** API keys grant full access to your topics. Keep them in
  environment variables or secrets managers on your server.
- **Rotate keys regularly.** Revoke and regenerate keys periodically, or immediately if you suspect
  a leak.
- **Use one key per integration.** Create separate keys for different services so you can revoke
  individual ones without affecting others.
- **Never commit keys to source control.** Use `.env` files and add them to `.gitignore`.

## Error Responses

Missing or invalid API keys return a `401 Unauthorized` response:

```json
{
  "error": {
    "message": "Unauthorized",
    "status": 401
  }
}
```

See the [Errors reference](https://ayewatch.ai/documentation/errors) for all status codes.