API Keys - Coval Documentation

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

You can also create and manage API keys from the dashboard. See the API Keys guide for instructions.

List API Keys

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

# 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

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

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

Key Types

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

# 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

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

# 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

coval api-keys delete <api_key_id>

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

coval api-keys delete ak_abc123

⌘I