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

# API Authentication

> Cost Optix supports API key authentication for programmatic access and CLI integration.

## Overview

The Cost Optix API uses **API keys** for authentication. API keys are scoped to your organization and carry a permission level that controls what operations they can perform.

API access is available on all tiers, with daily call limits depending on your plan:

| Tier         | Daily API call limit |
| ------------ | -------------------- |
| Starter      | 100                  |
| Professional | 1,000                |
| Business     | 10,000               |
| Enterprise   | Unlimited            |

***

## Generating an API Key

1. Log into your Cost Optix dashboard
2. Navigate to **Settings → API Keys**
3. Click **Create API Key**
4. Give it a descriptive name (e.g. `CI Pipeline`, `Grafana Integration`)
5. Select a permission level
6. Optionally set an expiry date
7. Copy the key immediately — it will not be shown again

***

## Permission Levels

| Permission | Description                                       |
| ---------- | ------------------------------------------------- |
| `read`     | View cost data, analytics, anomalies, and budgets |
| `write`    | Modify data and trigger operations                |
| `admin`    | Full access including API key management          |

***

## Using Your API Key

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

```bash theme={null}
curl -H "X-API-Key: cc_your_api_key_here" \
  https://costoptix.com/api/v1/health
```

<Warning>
  Never expose your API key in client-side code or public repositories. Treat it like a password.
</Warning>

***

## Base URL

```
https://costoptix.com/api/v1
```

***

## Example Requests

**Check authentication:**

```bash theme={null}
curl -H "X-API-Key: cc_your_key" \
  https://costoptix.com/api/v1/auth/info
```

**Get cost summary:**

```bash theme={null}
curl -H "X-API-Key: cc_your_key" \
  "https://costoptix.com/api/v1/costs?start_date=2025-01-01&end_date=2025-01-31"
```

***

## Key Rotation

API keys can be revoked at any time from **Settings → API Keys**. When rotating keys:

1. Create the new key
2. Update all systems using the old key
3. Revoke the old key

Revocation is immediate — the old key will stop working as soon as it is revoked.

***

## Rate Limiting

Requests that exceed your daily limit return a `429 Too Many Requests` response. The response includes a `Retry-After` header indicating when your quota resets (midnight UTC).

```json theme={null}
{
  "success": false,
  "error": "Daily API call limit reached. Upgrade your plan for higher limits."
}
```

***

## Error Responses

All API errors follow a consistent format:

```json theme={null}
{
  "success": false,
  "error": "Description of what went wrong"
}
```

| HTTP Status | Meaning                                            |
| ----------- | -------------------------------------------------- |
| `200`       | Success                                            |
| `400`       | Bad request — check your parameters                |
| `401`       | Unauthorized — invalid or missing API key          |
| `403`       | Forbidden — your key lacks the required permission |
| `429`       | Rate limit exceeded                                |
| `500`       | Internal server error                              |