# API Keys CLI

Use `provon api-keys` to manage project API keys and their usage policies.

These commands require a project-scoped credential.

## List API Keys

```bash
provon api-keys list
```

## Create An API Key

```bash
provon api-keys create --note "CI deployment"
```

Restrict capabilities with a comma-separated list:

```bash
provon api-keys create \
  --note "Read-only telemetry" \
  --capabilities telemetry:read
```

The default is all project API key capabilities. See [API authentication](../api/authentication.md)
for the capability model.

## Update An API Key

```bash
provon api-keys update <key-id> --note "Updated note"
```

## Revoke An API Key

```bash
provon api-keys revoke <key-id>
```

## Usage Policies

Usage policies limit how an API key can consume Gateway resources. Policies can act as rate limits or
budgets, scoped to the organization, project, key, or per-model.

Create a policy:

```bash
provon api-keys usage-policies create <key-id> \
  --scope-type project \
  --metric requests \
  --mode rate_limit \
  --limit 1000 \
  --window hour
```

Available scopes: `organization`, `project`, `api_key`, `model_per_organization`,
`model_per_project`, `model_per_api_key`.

Available metrics: `requests`, `tokens`, `cost_usd`.

Available modes: `rate_limit`, `budget`.

Available windows: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `custom`,
`lifetime`.

For `custom` windows, provide the length in seconds:

```bash
provon api-keys usage-policies create <key-id> \
  --scope-type api_key \
  --metric cost_usd \
  --mode budget \
  --limit 50 \
  --window custom \
  --custom-window-seconds 86400
```

Update a policy:

```bash
provon api-keys usage-policies update <key-id> <policy-id> \
  --limit 2000 \
  --window day \
  --enabled true
```

Delete a policy:

```bash
provon api-keys usage-policies delete <key-id> <policy-id>
```