# API Keys



Overview [#overview]

API keys are used to authenticate requests to the Kawn Console AI endpoints (Embeddings, OCR, etc.). Each key is scoped to an **organization** and grants access to all resources within it.

When you create an API key, the full key is displayed **only once**. After that, only a hint (the first few characters) is shown for identification. Store your key securely — it cannot be retrieved later.

***

Authentication [#authentication]

Include your API key in the `x-api-key` header:

```bash
curl https://api-dev.kawn.io/v1/embeddings \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "tbyaan/islamic-embedding-tbyaan-v1", "input": "..."}'
```

Alternatively, you can use the `Authorization` header with a `Bearer` prefix:

```bash
curl https://api-dev.kawn.io/v1/embeddings \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "tbyaan/islamic-embedding-tbyaan-v1", "input": "..."}'
```

<Callout type="info">
  API keys start with the `kc_` prefix. If you see a key that doesn't start with `kc_`, it may be invalid or from a different system.
</Callout>

***

Managing API Keys [#managing-api-keys]

Dashboard [#dashboard]

You can manage API keys from the **API Keys** page in the [Kawn Console dashboard](https://dashboard-dev.kawn.com). From there you can create new keys, see existing keys with their hints and creation dates, and delete keys you no longer need.

API Endpoints [#api-endpoints]

API key management is also available programmatically. These endpoints require **JWT authentication** (not API key auth) and the appropriate permissions.

***

Create API Key [#create-api-key]

```
POST /api-keys
```

Creates a new API key for the current organization.

**Required Permission:** `create-api-keys`

Request Body [#request-body]

| Field  | Type     | Required | Description                                        |
| ------ | -------- | -------- | -------------------------------------------------- |
| `name` | `string` | Yes      | A descriptive name for the key (2–100 characters). |

Response [#response]

```json
{
  "key": "kc_a1b2c3d4e5f6g7h8i9j0..."
}
```

| Field | Type     | Description                                                |
| ----- | -------- | ---------------------------------------------------------- |
| `key` | `string` | The full API key. **Shown only once** — store it securely. |

Example [#example]

```bash
curl -X POST https://api-dev.kawn.io/api-keys \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'
```

***

List API Keys [#list-api-keys]

```
GET /api-keys
```

Returns a paginated list of API keys for the current organization.

**Required Permission:** `get-api-keys`

Query Parameters [#query-parameters]

| Parameter | Type     | Default     | Description                         |
| --------- | -------- | ----------- | ----------------------------------- |
| `page`    | `number` | `1`         | Page number.                        |
| `perPage` | `number` | `10`        | Number of items per page.           |
| `order`   | `string` | `DESC`      | Sort direction (`ASC` or `DESC`).   |
| `orderBy` | `string` | `createdAt` | Sort field (`createdAt` or `name`). |
| `name`    | `string` | —           | Filter by name (substring match).   |

Response [#response-1]

```json
{
  "total": 2,
  "page": 1,
  "perPage": 10,
  "apiKeys": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "updatedAt": "2026-03-15T10:30:00.000Z",
      "name": "Production Key",
      "hint": "kc_a1b2c3d4e5"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "createdAt": "2026-03-20T14:00:00.000Z",
      "updatedAt": "2026-03-20T14:00:00.000Z",
      "name": "Development Key",
      "hint": "kc_x9y8z7w6v5"
    }
  ]
}
```

| Field                 | Type     | Description                                         |
| --------------------- | -------- | --------------------------------------------------- |
| `total`               | `number` | Total number of API keys.                           |
| `page`                | `number` | Current page number.                                |
| `perPage`             | `number` | Items per page.                                     |
| `apiKeys`             | `array`  | List of API key objects.                            |
| `apiKeys[].id`        | `string` | Key unique identifier.                              |
| `apiKeys[].name`      | `string` | Key name.                                           |
| `apiKeys[].hint`      | `string` | First few characters of the key for identification. |
| `apiKeys[].createdAt` | `string` | ISO 8601 creation timestamp.                        |
| `apiKeys[].updatedAt` | `string` | ISO 8601 last update timestamp.                     |

Example [#example-1]

```bash
curl "https://api-dev.kawn.io/api-keys?page=1&perPage=10" \
  -H "Authorization: Bearer <JWT_TOKEN>"
```

***

Delete API Key [#delete-api-key]

```
DELETE /api-keys/{id}
```

Permanently deletes an API key. Any requests using this key will immediately stop working.

**Required Permission:** `delete-api-keys`

Path Parameters [#path-parameters]

| Parameter | Type     | Required | Description               |
| --------- | -------- | -------- | ------------------------- |
| `id`      | `string` | Yes      | The API key ID to delete. |

Response [#response-2]

```json
{
  "message": "Api key deleted successfully."
}
```

Example [#example-2]

```bash
curl -X DELETE https://api-dev.kawn.io/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <JWT_TOKEN>"
```

***

Security Best Practices [#security-best-practices]

* **Never commit API keys to version control.** Use environment variables or a secrets manager.
* **Rotate keys periodically.** Create a new key, update your applications, then delete the old one.
* **Use descriptive names.** Name keys after the service or environment they're used in (e.g., "Production Backend", "Staging CI/CD").
* **Limit access.** Assign the `create-api-keys`, `get-api-keys`, and `delete-api-keys` permissions only to roles that need them.