Authentication

API Keys

All API requests require an API key passed as a Bearer token. Keys are created in the LevelFour dashboard under Settings > API Keys.

Key Formats

Prefix	Environment	Use Case
`l4_live_`	Production	Live data, real optimizations
`l4_test_`	Test	Safe for development, no side effects

Each key has a scope that controls what it can do. Set it when you create the key. The default is read. The API and SDKs use the values read and read-write. The dashboard shows the same two scopes as Read-only and Read & write.

Scope (API value)	Dashboard label	Allowed
`read`	Read-only	All read endpoints: list and fetch costs, recommendations, savings, providers, commitments, and anomalies.
`read-write`	Read & write	Everything a `read` key can do, plus the endpoints that change state, such as applying or executing a recommendation.

A read key that calls a write endpoint receives 403 Forbidden with the detail API key scope insufficient. Create read-only keys for monitoring, dashboards, and CI checks, and reserve read-write keys for automation that applies changes.

Managing keys (creating, listing, rotating, and revoking) is available only to signed-in dashboard users, never to API keys, regardless of scope.

Configuration

Environment Variable (Recommended)

All SDKs auto-detect the LEVELFOUR_API_KEY environment variable:

export LEVELFOUR_API_KEY="l4_live_your_key_here"

from levelfour import LevelFour

client = LevelFour()

Explicit API Key

Pass the key directly to the constructor:

client = LevelFour(api_key="l4_live_your_key_here")

Verifying Your Key

Use the whoami endpoint to verify your API key is valid:

me = client.auth.get_whoami()
print(me)

Managing API Keys

Create a Key

key = client.api_keys.create(name="CI Pipeline", scope="read")
print(key)

List Keys

keys = client.api_keys.list()

Rotate a Key

Rotation creates a new secret for the same key ID. The old secret is immediately invalidated.

rotated = client.api_keys.rotate(key_id="key_123")

Store the new key immediately after rotation. It will not be shown again.

Revoke a Key

client.api_keys.revoke(key_id="key_123")

Security Best Practices

Never commit API keys to version control. Use environment variables or secrets managers.
Use l4_test_ keys in development and CI/CD pipelines.
Rotate keys immediately if you suspect they have been compromised.
Use scoped keys - create read-only keys for monitoring and read-write keys only where mutations are needed.
Set expiration dates on keys that are used for temporary integrations.