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

# API Keys

> Manage API keys for programmatic access with the Coval CLI

API keys provide programmatic access to the Coval API. You can create keys scoped to specific environments and permissions.

<Tip>
  You can also create and manage API keys from the dashboard. See the [API Keys guide](/guides/api-keys) for instructions.
</Tip>

## List API Keys

```bash theme={null}
coval api-keys list [OPTIONS]
```

| Option          | Type   | Default | Description                                                    |
| --------------- | ------ | ------- | -------------------------------------------------------------- |
| `--filter`      | string | —       | Filter expression                                              |
| `--page-size`   | number | 50      | Results per page                                               |
| `--order-by`    | string | —       | Sort order                                                     |
| `--status`      | string | —       | Filter by status (`active`, `revoked`, `suspended`, `expired`) |
| `--environment` | string | —       | Filter by environment (`production`, `staging`, `development`) |

**Output columns:** ID, NAME, TYPE, ENV, STATUS, PERMISSIONS, LAST USED

```bash theme={null}
# List all API keys
coval api-keys list

# Filter by environment
coval api-keys list --environment production

# List only active keys
coval api-keys list --status active
```

## Create API Key

```bash theme={null}
coval api-keys create [OPTIONS]
```

| Option          | Type   | Required | Description                                                 |
| --------------- | ------ | -------- | ----------------------------------------------------------- |
| `--name`        | string | **Yes**  | Display name for the key                                    |
| `--description` | string | No       | Optional description                                        |
| `--type`        | string | **Yes**  | Key type (`service` or `user`)                              |
| `--environment` | string | **Yes**  | Target environment (`production`, `staging`, `development`) |
| `--permissions` | string | No       | Comma-separated permission scopes                           |

<Warning>
  The full API key is only shown once at creation time. Store it securely — it cannot be retrieved later.
</Warning>

### Key Types

| Type      | Description                                           |
| --------- | ----------------------------------------------------- |
| `service` | For server-to-server integrations and CI/CD pipelines |
| `user`    | For individual user access                            |

```bash theme={null}
# Create a production service key
coval api-keys create \
  --name "CI Pipeline" \
  --type service \
  --environment production

# Create a development key with description
coval api-keys create \
  --name "Dev Testing" \
  --type user \
  --environment development \
  --description "Key for local development"
```

## Update API Key

```bash theme={null}
coval api-keys update <api_key_id> [OPTIONS]
```

| Argument     | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `api_key_id` | string | **Yes**  | The API key ID to update |

| Option     | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `--status` | string | **Yes**  | New status (`active`, `revoked`, `suspended`, `expired`) |
| `--reason` | string | No       | Reason for the status change                             |

```bash theme={null}
# Revoke a key
coval api-keys update ak_abc123 --status revoked

# Revoke with a reason
coval api-keys update ak_abc123 --status revoked --reason "Key compromised"
```

## Delete API Key

```bash theme={null}
coval api-keys delete <api_key_id>
```

| Argument     | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `api_key_id` | string | **Yes**  | The API key ID to delete |

```bash theme={null}
coval api-keys delete ak_abc123
```