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

# API keys

> Organization API keys for agents and CI. Keys carry a member or admin role, authorize only their own organization, and can never manage keys, billing, or members.

Organization API keys for agents and CI. Keys carry a member or admin role, authorize only their own organization, and can never manage keys, billing, or members.

## apikeys.list

List the organization's API keys. Secrets are never shown — only prefixes.

```text theme={null}
GET /v1/orgs/{orgId}/api-keys
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/api-keys" \
  -b "$SESSION"
```

### Responses

| Status | Description                       |
| ------ | --------------------------------- |
| `200`  | API keys, including revoked ones. |

### Response body (200)

An array of objects with these fields:

| Field        | Type           | Description                                                                                           |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------- |
| `id`         | string         | —                                                                                                     |
| `name`       | string         | —                                                                                                     |
| `keyPrefix`  | string         | Display handle for the key, e.g. "korve\_ab12…". Never the secret.                                    |
| `role`       | string         | Role ceiling the key authenticates with. Defaults to "admin"; never owner. One of: `member`, `admin`. |
| `lastUsedAt` | string or null | Format: `date-time`.                                                                                  |
| `revokedAt`  | string or null | Format: `date-time`.                                                                                  |
| `createdAt`  | string         | Format: `date-time`.                                                                                  |

## apikeys.create

Create an API key. The full secret is shown once and never retrievable later.

```text theme={null}
POST /v1/orgs/{orgId}/api-keys
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `write` · sensitive (elevated blast radius)

### Request body

| Field  | Type   | Required | Description                                                                                           |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `name` | string | Yes      | Display name, 1-100 characters. Pattern: `^.{1,100}$`.                                                |
| `role` | string | No       | Role ceiling the key authenticates with. Defaults to "admin"; never owner. One of: `member`, `admin`. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/api-keys" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "role": "member"
}'
```

### Responses

| Status | Description                                                                        |
| ------ | ---------------------------------------------------------------------------------- |
| `201`  | API key created. `key` is the full secret — shown exactly once; store it securely. |
| `422`  | Invalid name or role (owner keys do not exist).                                    |

### Response body (201)

| Field       | Type   | Description                                                                                           |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `id`        | string | —                                                                                                     |
| `name`      | string | —                                                                                                     |
| `keyPrefix` | string | Display handle for the key, e.g. "korve\_ab12…". Never the secret.                                    |
| `role`      | string | Role ceiling the key authenticates with. Defaults to "admin"; never owner. One of: `member`, `admin`. |
| `key`       | string | The full secret. Shown exactly once — it is never retrievable later. Pattern: `^korve_[0-9a-f]{40}$`. |

## apikeys.revoke

Revoke an API key. The key stops authenticating immediately; revoking an already-revoked key returns the same revocation time (idempotent).

```text theme={null}
DELETE /v1/orgs/{orgId}/api-keys/{keyId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `admin`
* **Risk:** `write` · sensitive (elevated blast radius)

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/api-keys/$KEY_ID" \
  -b "$SESSION"
```

### Responses

| Status | Description                           |
| ------ | ------------------------------------- |
| `200`  | Key revoked (or already was).         |
| `404`  | No such API key in this organization. |

### Response body (200)

| Field       | Type   | Description          |
| ----------- | ------ | -------------------- |
| `revokedAt` | string | Format: `date-time`. |