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

# Authentication

> How to authenticate with the Wardin API.

## API Keys

All requests to `api.wardin.ai/v1/` use Bearer token authentication:

```bash theme={null}
Authorization: Bearer wardin_sk_YOUR_KEY
```

The same `wardin_sk_` keys used to authenticate with the gateway also work with the management API. The key's permissions determine what operations are allowed.

## Key prefixes

| Prefix       | Type        | Used for                             |
| ------------ | ----------- | ------------------------------------ |
| `wardin_sk_` | Virtual key | Gateway proxy calls + management API |

<Warning>
  Register the `wardin_sk_` prefix with your secret scanner (GitHub Advanced Security, truffleHog, Gitleaks) to prevent accidental commits.
</Warning>

## Key permissions

| Operation                         | Permission required                           |
| --------------------------------- | --------------------------------------------- |
| Create / update / delete keys     | Manager                                       |
| Create / update / delete policies | Manager                                       |
| Create / update / delete budgets  | Manager                                       |
| Approve / deny budget requests    | Manager                                       |
| Read analytics                    | Any valid key                                 |
| List keys                         | Any valid key (own keys only, unless manager) |

## Example request

```bash theme={null}
curl https://api.wardin.ai/v1/keys \
  -H "Authorization: Bearer wardin_sk_YOUR_KEY" \
  -H "Content-Type: application/json"
```

## Error responses

Missing key:

```json theme={null}
{
  "error": {
    "type": "unauthorized",
    "message": "Missing or invalid API key.",
    "code": 401
  }
}
```

Insufficient permissions:

```json theme={null}
{
  "error": {
    "type": "forbidden",
    "message": "This operation requires manager-level access.",
    "code": 403
  }
}
```

## Rotating keys

There is no in-place rotation — create a new key, update your environment, then revoke the old one:

```bash theme={null}
# 1. Create a new key
curl -X POST https://api.wardin.ai/v1/keys \
  -H "Authorization: Bearer wardin_sk_OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "admin-rotated"}'

# 2. Update your WARDIN_API_KEY env var to the new key

# 3. Revoke the old key
curl -X DELETE https://api.wardin.ai/v1/keys/key_OLD_ID \
  -H "Authorization: Bearer wardin_sk_NEW_KEY"
```