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

# API Key Management

> Validate your key, check usage, or create new keys.

## Endpoints

| Method | Path                 | Description                                        |
| ------ | -------------------- | -------------------------------------------------- |
| `GET`  | `/api/keys/validate` | Check if a key is active and retrieve its metadata |
| `GET`  | `/api/keys/usage`    | Get monthly usage history for a key                |
| `GET`  | `/api/keys/create`   | Create a new API key (admin only)                  |

***

## Validate a key

<api>GET [https://app.airrating.io/api/keys/validate](https://app.airrating.io/api/keys/validate)</api>

Check whether an API key is valid and retrieve its metadata.

### Request

<ParamField query="api_key" type="string" required>
  The API key to validate.
</ParamField>

### Response

<ResponseField name="valid" type="boolean">
  `true` if the key is active, `false` otherwise.
</ResponseField>

<ResponseField name="prefix" type="string">
  The first 14 characters of the key (safe to display/log).
</ResponseField>

<ResponseField name="name" type="string">
  Label assigned to the key when it was created.
</ResponseField>

<ResponseField name="monthly_limit" type="integer">
  Maximum number of API calls per calendar month.
</ResponseField>

<ResponseField name="month_count" type="integer">
  Number of calls made in the current calendar month.
</ResponseField>

<ResponseField name="total_requests" type="integer">
  Total API calls made with this key across all time.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the key was created.
</ResponseField>

### Example

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

```json theme={null}
{
  "valid": true,
  "prefix": "ar_live_xxxxxx",
  "name": "My Integration",
  "monthly_limit": 1000,
  "month_count": 42,
  "total_requests": 387,
  "created_at": "2026-01-15T10:30:00Z"
}
```

***

## Get usage history

<api>GET [https://app.airrating.io/api/keys/usage](https://app.airrating.io/api/keys/usage)</api>

Returns current-month usage and up to 24 months of historical usage for your key.

### Request

<ParamField query="api_key" type="string" required>
  Your API key.
</ParamField>

<ParamField query="year" type="integer">
  Filter history to a specific year (optional).
</ParamField>

<ParamField query="month" type="integer">
  Filter history to a specific month, 1–12 (optional).
</ParamField>

### Response

<ResponseField name="key_prefix" type="string">
  Key prefix identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Key label.
</ResponseField>

<ResponseField name="current_month" type="object">
  Usage for the current calendar month.

  <Expandable title="current_month fields">
    <ResponseField name="year" type="integer">Current year.</ResponseField>
    <ResponseField name="month" type="integer">Current month (1–12).</ResponseField>
    <ResponseField name="requests" type="integer">Calls made so far this month.</ResponseField>
    <ResponseField name="monthly_limit" type="integer">Monthly call limit.</ResponseField>
    <ResponseField name="period" type="string">Always `"current"`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="history" type="array">
  Past months, up to 24 entries, most recent first.

  <Expandable title="History entry">
    <ResponseField name="year" type="integer">Year.</ResponseField>
    <ResponseField name="month" type="integer">Month (1–12).</ResponseField>
    <ResponseField name="requests" type="integer">Total calls in that month.</ResponseField>
    <ResponseField name="monthly_limit" type="integer">Limit at that time.</ResponseField>
    <ResponseField name="usage_pct" type="float">Percentage of limit consumed.</ResponseField>
    <ResponseField name="logged_at" type="string">ISO 8601 timestamp when the record was logged.</ResponseField>
    <ResponseField name="period" type="string">Always `"historical"`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_requests_all_time" type="integer">
  Cumulative total calls across all months.
</ResponseField>

### Example

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

```json theme={null}
{
  "key_prefix": "ar_live_xxxxxx",
  "name": "My Integration",
  "current_month": {
    "year": 2026,
    "month": 4,
    "requests": 87,
    "monthly_limit": 1000,
    "period": "current"
  },
  "history": [
    {
      "year": 2026,
      "month": 3,
      "requests": 312,
      "monthly_limit": 1000,
      "usage_pct": 31.2,
      "logged_at": "2026-04-01T00:05:00Z",
      "period": "historical"
    }
  ],
  "total_requests_all_time": 399
}
```

***

## Create a key

<api>GET [https://app.airrating.io/api/keys/create](https://app.airrating.io/api/keys/create)</api>

<Warning>
  This endpoint is restricted to admin use during private beta. It is not available to general API users.
</Warning>

Creates a new API key and stores it in the database.

### Request

<ParamField query="name" type="string" required>
  A label for the key (e.g. company name or integration name).
</ParamField>

<ParamField query="email" type="string" required>
  Contact email associated with the key.
</ParamField>

<ParamField query="monthly_limit" type="integer" default="100">
  Maximum API calls per calendar month.
</ParamField>

### Response

<ResponseField name="api_key" type="string">
  The newly created API key. **Store this immediately — it cannot be retrieved again.**
</ResponseField>

<ResponseField name="prefix" type="string">
  The first 14 characters (safe reference).
</ResponseField>

<ResponseField name="monthly_limit" type="integer">
  Monthly request limit.
</ResponseField>

<ResponseField name="message" type="string">
  Reminder to save the key.
</ResponseField>

### Example

```json theme={null}
{
  "api_key": "ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "ar_live_xxxxxx",
  "monthly_limit": 100,
  "message": "Save this key — it will NOT be shown again."
}
```