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

# Authentication

> How to authenticate requests to the AirRating API.

## API keys

All API requests require a valid API key passed as the `api_key` query parameter.

```bash theme={null}
curl "https://app.airrating.io/api/score?origin=FCO&dest=LHR&airline=AZ&date=2026-04-10&api_key=YOUR_API_KEY"
```

<Note>
  Header-based authentication (`Authorization: Bearer`) is planned for a future release. During beta, use the `api_key` query parameter.
</Note>

## Key format

```
ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Keys are prefixed with `ar_live_` for production and `ar_test_` for sandbox/testing.

## Getting a key

During private beta, keys are provisioned manually:

1. Join the waitlist at [airrating.io](https://airrating.io)
2. Once accepted into the beta, you will receive your key via email
3. You can also request access directly at [hello@airrating.io](mailto:hello@airrating.io)

## Validating a key

Check whether a key is active and retrieve its metadata:

```bash theme={null}
curl "https://app.airrating.io/api/keys/validate?api_key=YOUR_API_KEY"
```

```json theme={null}
{
  "valid": true,
  "name": "My Integration",
  "monthly_limit": 1000,
  "requests_this_month": 42
}
```

## Rate limits

| Plan                 | Monthly requests |
| -------------------- | ---------------- |
| Beta                 | 1,000            |
| Starter (planned)    | 10,000           |
| Pro (planned)        | 100,000          |
| Enterprise (planned) | Unlimited        |

When you exceed your monthly limit, the API returns HTTP `429`:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Monthly request limit reached. Contact hello@airrating.io to upgrade."
}
```

## Error responses

| HTTP code | Error code            | Meaning                         |
| --------- | --------------------- | ------------------------------- |
| `401`     | `missing_api_key`     | No `api_key` parameter provided |
| `401`     | `invalid_api_key`     | Key not found or inactive       |
| `429`     | `rate_limit_exceeded` | Monthly limit exhausted         |
| `500`     | `internal_error`      | Server-side error               |

## Security best practices

<Warning>
  Never expose your API key in frontend JavaScript, public GitHub repositories, or client-side code.
</Warning>

* Store keys in environment variables (`.env`) and never commit them to version control
* Use a backend proxy to call the AirRating API from your application
* Rotate your key immediately if you suspect it has been compromised — contact [hello@airrating.io](mailto:hello@airrating.io)