API keys

API keys are the primary authentication mechanism for the CLIMeter SDK and API. Every consumer of a metered tool authenticates with an API key, and builders use their key to manage tools and account settings.

Creating keys

Create keys from the dashboard under Settings → API Keys, or via the API:

Bash

curl -X POST https://api.climeter.ai/v1/keys \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production key",
    "scopes": ["events:write"]
  }'

# Response
{
  "key": "clmtr_live_abc123xyz...",
  "key_id": "key_01HXZ...",
  "name": "Production key",
  "created_at": "2025-03-07T12:00:00Z"
}

Save the key now

The full key value is only shown once at creation. Store it immediately in a secrets manager. If lost, you must rotate (create a new one and revoke the old one).

Key types

Prefix	Type	Usage
clmtr_	API key	SDK usage and API calls — set as CLIMETER_API_KEY

Scoping keys

Keys can be scoped to limit what they can do. Always issue the minimum required scope.

Scope	Description
events:write	Record metering events (required for SDK usage)
events:read	Read event history
tools:read	List and read tool configurations
tools:write	Create and update tools
billing:read	Read billing and usage data
billing:write	Manage billing configuration
keys:manage	Create and revoke API keys

Rotating keys

Rotate keys by creating a new one and updating your deployment before revoking the old one. CLIMeter supports a brief overlap period to enable zero-downtime rotation.

Bash

# 1. Create new key via dashboard or API
# 2. Update your deployment: export CLIMETER_API_KEY=clmtr_new_key
# 3. Verify traffic is flowing with the new key
# 4. Revoke the old key via dashboard

Revoking keys

Revocation is immediate and permanent. Any in-flight request using the revoked key will receive a 401 Unauthorized response. Revoke from the dashboard or via API:

Bash

curl -X DELETE https://api.climeter.ai/v1/keys/key_01HXZ... \
  -H "Authorization: Bearer <jwt>"

# Response
{ "revoked": true, "key_id": "key_01HXZ..." }

Warning

Revocation cannot be undone. The key is permanently invalidated. Create a new key before revoking if you need continued access.