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

# Authentication

> How to authenticate with the AIOKA Intelligence API

# Authentication

All AIOKA Intelligence API endpoints (except `/v1/health` and `/v1/keys/generate`)
require an API key passed in the `X-API-Key` header.

## API Key Format

```
aik_{tier}_{20 random characters}
```

**Examples:**

* `aik_free_a1b2c3d4e5f6g7h8i9j0` — Free tier
* `aik_basic_x9y8z7w6v5u4t3s2r1q0` — Basic tier
* `aik_pro_m1n2o3p4q5r6s7t8u9v0` — Pro tier

## Making Authenticated Requests

Include your key in the `X-API-Key` header on every request:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.aioka.io/v1/verdict/latest \
    -H "X-API-Key: aik_free_your_key_here"
  ```

  ```python Python theme={null}
  import httpx

  client = httpx.Client(
      base_url="https://api.aioka.io",
      headers={"X-API-Key": "aik_free_your_key_here"},
  )

  resp = client.get("/v1/verdict/latest")
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch(
    "https://api.aioka.io/v1/verdict/latest",
    {
      headers: { "X-API-Key": "aik_free_your_key_here" },
    }
  );
  const data = await resp.json();
  ```
</CodeGroup>

## Error Responses

| Status | Error                  | Cause                           |
| ------ | ---------------------- | ------------------------------- |
| `401`  | `missing_api_key`      | No `X-API-Key` header           |
| `401`  | `invalid_api_key`      | Key not found in database       |
| `401`  | `key_inactive`         | Key has been deactivated        |
| `403`  | `tier_required`        | Endpoint requires a higher tier |
| `429`  | `daily_limit_exceeded` | Daily call quota exhausted      |
| `429`  | `rate_limit_exceeded`  | Per-minute rate limit hit       |

## Security

* Store your key securely — treat it like a password
* Never commit it to version control
* Use environment variables: `export AIOKA_API_KEY=aik_free_...`
* The key is shown **once** at generation and cannot be recovered

## Get Your Free Key

```bash theme={null}
curl -X POST https://api.aioka.io/v1/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "email": "you@example.com"}'
```

[→ Full key generation docs](/api-reference/keys/generate)