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

# API Keys

> Create and manage API keys to authenticate your agent calls

API keys authenticate your requests to agents through the Kovrex gateway. Each key is scoped to a specific agent subscription and can have its own rate limits and IP restrictions.

You can create multiple keys per agent for different use cases:

* **Production** — locked to your server IPs, higher rate limits
* **Development** — unrestricted IPs, lower rate limits
* **Partner integrations** — separate keys for each partner with their own limits

## Creating an API Key

<Steps>
  <Step title="Navigate to API Keys">
    Go to **Dashboard → API Keys** and click **Create API Key**.
  </Step>

  <Step title="Select an agent">
    Choose which agent this key will access. You can only create keys for agents you have an active subscription to.
  </Step>

  <Step title="Configure the key">
    * **Name** — A descriptive name (e.g., "Production Server", "Dev Environment")
    * **Expiration** — Optional expiration date
    * **Rate limits** — Custom per-minute and per-day limits, or use subscription defaults
    * **IP restrictions** — Lock the key to specific IPs or allow any IP
  </Step>

  <Step title="Copy your key">
    Your full API key is shown **only once**. Copy it immediately and store it securely.

    ```
    kvx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
    ```
  </Step>
</Steps>

<Warning>
  **Store your key securely.** We only store a hash of your key and cannot retrieve or display it again. If you lose a key, you'll need to regenerate it.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header:

```bash theme={null}
curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \
  -H "Authorization: Bearer kvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "your request"}'
```

Or use the `X-Kovrex-Key` header:

```bash theme={null}
curl -X POST https://gateway.kovrex.ai/v1/agents/{agent_id}/invoke \
  -H "X-Kovrex-Key: kvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "your request"}'
```

## IP Restrictions

IP restrictions limit which IP addresses can use a key. This is strongly recommended for production keys.

### Adding IP Restrictions

You can specify:

* **Individual IPs** — `192.168.1.100`
* **CIDR ranges** — `10.0.0.0/8` (allows 10.0.0.0 - 10.255.255.255)

Common CIDR ranges:

| CIDR  | Range      | Use case             |
| ----- | ---------- | -------------------- |
| `/32` | Single IP  | One server           |
| `/24` | 256 IPs    | Small subnet         |
| `/16` | 65,536 IPs | Large network        |
| `/8`  | 16.7M IPs  | Cloud provider range |

### Best Practices

<CardGroup cols={2}>
  <Card title="Do" icon="check" color="#22c55e">
    * Use IP restrictions for all production keys
    * Use CIDR ranges for dynamic cloud environments
    * Create separate keys for each environment
  </Card>

  <Card title="Don't" icon="xmark" color="#ef4444">
    * Use unrestricted keys in production
    * Share keys across teams or partners
    * Commit keys to version control
  </Card>
</CardGroup>

### Unrestricted Keys

Keys without IP restrictions can be used from any IP address. Only use these for:

* Local development
* Environments where IP restrictions aren't feasible
* Testing and prototyping

<Warning>
  Unrestricted keys are a security risk. If leaked, anyone can use them to make requests on your behalf.
</Warning>

## Rate Limits

Rate limits protect both you and the agent operators from excessive usage.

### How Rate Limits Work

Each key has two limits:

* **Per-minute** — Maximum requests in a 60-second sliding window
* **Per-day** — Maximum requests in a calendar day (UTC)

You can set custom limits per key, or use your subscription's defaults.

### Rate Limit Headers

Every response includes rate limit headers:

```
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 45
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 8234
```

Use these headers to implement client-side throttling before hitting limits.

### Handling Rate Limits

When you exceed a rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded (per minute)",
    "retry_after": 12
  }
}
```

**Recommended handling:**

```python theme={null}
import time
import requests

def call_agent_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 10))
            time.sleep(retry_after)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")
```

## Managing Keys

### Viewing Key Details

Go to **Dashboard → API Keys** to see all your keys with:

* Usage stats (calls today, calls this month)
* Last used timestamp
* Configuration (rate limits, IP restrictions, expiration)

### Updating a Key

You can update a key's:

* Name
* Rate limits
* IP restrictions

Changes take effect within 30 seconds.

<Note>
  You cannot change which agent a key is scoped to. Create a new key for a different agent.
</Note>

### Regenerating a Key

If a key is compromised or you need to rotate it:

1. Click the **⋮** menu on the key card
2. Select **Regenerate**
3. Copy the new key immediately

The old key is revoked instantly. Update your applications with the new key.

<Tip>
  **Zero-downtime rotation:** Create a new key first, update your applications, then revoke the old key.
</Tip>

### Revoking a Key

To permanently disable a key:

1. Click the **⋮** menu on the key card
2. Select **Revoke**

Revoked keys cannot be restored. Any requests using the key will immediately receive a `401 Unauthorized` response.

## Error Responses

| Status | Code                    | Description                        |
| ------ | ----------------------- | ---------------------------------- |
| `401`  | `missing_api_key`       | No API key provided                |
| `401`  | `invalid_api_key`       | Key doesn't exist or is malformed  |
| `401`  | `revoked_api_key`       | Key has been revoked               |
| `401`  | `expired_api_key`       | Key has passed its expiration date |
| `403`  | `ip_not_allowed`        | Request IP not in key's allowlist  |
| `403`  | `subscription_inactive` | Agent subscription is not active   |
| `429`  | `rate_limit_minute`     | Per-minute rate limit exceeded     |
| `429`  | `rate_limit_day`        | Per-day rate limit exceeded        |

## Billing

API key usage is tracked for billing purposes. On the **Billing** page, you can see:

* Total calls and cost per agent
* Breakdown by individual key
* Daily and monthly trends

This helps you attribute costs to specific projects, environments, or integrations.

## Security Checklist

<AccordionGroup>
  <Accordion title="Production deployment">
    * [ ] Use IP-restricted keys
    * [ ] Set appropriate rate limits
    * [ ] Store keys in environment variables or secrets manager
    * [ ] Never commit keys to version control
    * [ ] Use separate keys for each environment
  </Accordion>

  <Accordion title="Team access">
    * [ ] Create separate keys for each team member or integration
    * [ ] Use descriptive names to track ownership
    * [ ] Revoke keys when team members leave
    * [ ] Review active keys quarterly
  </Accordion>

  <Accordion title="Incident response">
    * [ ] Monitor for unusual usage patterns
    * [ ] Have a process to quickly revoke compromised keys
    * [ ] Know how to regenerate keys without downtime
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How many keys can I create?">
    There's no hard limit on keys per agent. Create as many as you need for your use cases.
  </Accordion>

  <Accordion title="Can one key access multiple agents?">
    No, each key is scoped to a single agent. Create separate keys for each agent you subscribe to.
  </Accordion>

  <Accordion title="What happens when a key expires?">
    Expired keys stop working immediately. You'll receive a `401 expired_api_key` error. Create a new key to continue access.
  </Accordion>

  <Accordion title="Can I see which IP addresses used my key?">
    Yes, the usage logs show the source IP for each request. Contact support for detailed access logs.
  </Accordion>

  <Accordion title="How do I rotate keys without downtime?">
    Create a new key, update your application to use both keys (fallback pattern), deploy, then revoke the old key.
  </Accordion>
</AccordionGroup>