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

# Authenticate with the Knouds API

> Generate Knouds API keys in the Developer Dashboard, pass them via the x-api-key header, and understand the capability system that gates each endpoint.

Knouds workflows and models are reachable from any external system through a REST API. To call the API, you generate a key, attach it to your requests with the `x-api-key` header, and your account must hold the right capabilities for the endpoint. This page covers each step end-to-end.

## Generate a key

Sign in to [knouds.ai](https://knouds.ai) and open the [Developer Dashboard](https://knouds.ai/app/api/keys) (also accessible from **Settings → API Keys**, which redirects). Click **Create Key** and pick a preset:

| Preset               | Capabilities granted                              |
| -------------------- | ------------------------------------------------- |
| **Read-only**        | `workflow:read`                                   |
| **Workflow Deploy**  | `workflow:run`, `workflow:read`                   |
| **Webhook receiver** | `webhook:receive`                                 |
| **Full deploy**      | `workflow:run`, `workflow:read`, `workflow:write` |
| **Custom**           | Any subset capped by your tier ceiling            |

The plaintext key is shown only once at creation — copy it immediately and store it safely. If you lose it, revoke the key and generate a new one.

<Warning>
  Free tier cannot create usable API keys. The Free API key ceiling is empty by product design — Free users save and run workflows from the canvas (browser session). Pro+ unlocks key creation.
</Warning>

## Send your key

Pass the key in the `x-api-key` request header:

```
x-api-key: YOUR_KEY
```

Every authenticated API endpoint accepts this header. Requests without a valid key — or with a key whose capabilities don't cover the endpoint — receive a `401` or `403` response.

## Capabilities

Each key carries a SET of capabilities, granted at creation time. Capabilities are **orthogonal** — a key with `model:run` does not automatically get `workflow:write`. Mix and match by use case (read-only audit key, single-flow CI key, full deploy key).

| Capability            | Plan tier  | Reaches                                          |
| --------------------- | ---------- | ------------------------------------------------ |
| `workflow:run`        | Pro        | Run any of your deployed workflows               |
| `workflow:read`       | Pro        | List workflows, read schemas                     |
| `workflow:write`      | Pro        | Create, update, delete (ownership-checked)       |
| `workflow:<slug>:run` | Pro        | Specific flow only (least-privilege CI keys)     |
| `model:run`           | Business   | Run any registry model                           |
| `model:<id>:run`      | Business   | Specific model only                              |
| `webhook:receive`     | Pro        | Receive outbound webhooks for `?async=true` runs |
| `execution:read`      | every tier | Poll your own async executions                   |
| `execution:cancel`    | every tier | Cancel your own in-flight executions             |

If your key's capability set does not cover the endpoint you're calling, the API returns:

```json theme={null}
{
  "error": "Insufficient capability",
  "code": "CAPABILITY_DENIED",
  "required": "workflow:run"
}
```

The `required` field tells you exactly which capability would have passed. Either regenerate the key with broader capabilities (capped by your tier) or upgrade your tier.

See [API Reference → Authentication](/api/authentication) for the full capability vocabulary, match logic, and error responses.

## Rotate or revoke a key

Keys never expire automatically. To rotate:

1. Open the [Developer Dashboard](https://knouds.ai/app/api/keys)
2. Click **Revoke** on the old key
3. Click **Create Key** to generate a replacement
4. Update your integration's `x-api-key` header