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

# Scoped API Keys

> Create and manage API keys with fine-grained permissions

## Overview

Scoped API keys let you create multiple keys with specific permissions for different use cases:

* **CI/CD Pipeline**: `incidents:write` only — can create incidents but can't read services
* **Dashboard Widget**: `incidents:read`, `services:read` — read-only access for displays
* **Monitoring Agent**: `heartbeat:write`, `metrics:write` — can send data but can't modify anything

## Creating a Key

### Via Dashboard

1. Navigate to **Settings > API Keys**
2. Click **Create Key**
3. Enter a descriptive name
4. Select the permissions your key needs
5. Optionally set an expiry date
6. Click **Create Key**
7. Copy the key immediately — it will only be shown once

### Via API

```bash theme={null}
curl -X POST "https://kodostatus.com/api/v1/api-keys" \
  -H "X-API-Key: your_full_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["incidents:write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'
```

The response includes the plaintext key (returned only once):

```json theme={null}
{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "key": "kodo_abc123...",
  "key_prefix": "kodo_abc123..",
  "scopes": ["incidents:write"],
  "enabled": true,
  "created_at": "2026-02-21T00:00:00Z"
}
```

## Managing Keys

### List Keys

```bash theme={null}
curl "https://kodostatus.com/api/v1/api-keys" \
  -H "X-API-Key: your_api_key"
```

### Disable a Key

```bash theme={null}
curl -X PATCH "https://kodostatus.com/api/v1/api-keys/{id}" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

### Delete a Key

```bash theme={null}
curl -X DELETE "https://kodostatus.com/api/v1/api-keys/{id}" \
  -H "X-API-Key: your_api_key"
```

## Plan Limits

| Plan       | Max Keys        |
| ---------- | --------------- |
| Starter    | Legacy key only |
| Pro        | 5 scoped keys   |
| Team       | 25 scoped keys  |
| Enterprise | Unlimited       |

## Best Practices

* **Principle of least privilege**: Give each key only the scopes it needs
* **Set expiry dates**: Rotate keys regularly, especially for CI/CD
* **Use descriptive names**: Name keys after their purpose (e.g., "GitHub Actions Deploy")
* **Monitor usage**: Check `last_used_at` to identify unused keys
* **Disable before deleting**: Disable a key first to verify nothing breaks before permanent removal