Authentication
Every request to the LevelFour API carries an API key. The prefix on the key says which environment it reaches, and the scope on it says what it may do there.
API keys
Create keys in the LevelFour dashboard under Settings > API Keys, and pass one as a Bearer token.
Key formats
| Prefix | Environment | Use Case |
|---|---|---|
l4_live_ | Production | Live data, real optimizations |
l4_test_ | Test | Safe for development, no side effects |
Key scopes
Each key carries a scope, set when you create it. The default is read. The API and SDKs take the values read and read-write, and the dashboard shows the same two 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 in LevelFour: accepting or rejecting a recommendation, adding rejection feedback, curating the resources a saving applies to, choosing an implementation method, and requesting execution. |
read key that calls a write endpoint receives 403 Forbidden with the detail API key scope insufficient.No key of either scope changes anything in your cloud account. Requesting execution starts the rollout in LevelFour and moves the recommendation's implementation to in progress; the step that reaches into your account is the savings grant, and that requires a signed-in administrator holding org:savings:execute. An API key is refused there.
Create read-only keys for monitoring, dashboards, and CI checks, and reserve read-write keys for automation that records decisions.
The MCP server takes these keys too, alongside its own sign-in flow, and its write surface is narrower than the one above: it records a decision and nothing else, with no way to request execution. Connecting a client compares the two credentials and says which scope each tool needs.
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
Call the whoami endpoint:
me = client.auth.get_whoami()
print(me)whoami is the proof the key is live. A data endpoint is weaker evidence, because it can fail for reasons that have nothing to do with the credential.Managing API keys
API Keys has the SDK method for each of those, its parameters, and the optional expiration date.
Key rotation
Rotation creates a new secret for the same key ID. The old secret is immediately invalidated.
Security best practices
Reach for an l4_test_ key in development and in CI/CD pipelines. Set an expiration date on any key you mint for a temporary integration.
Next
- API Keys is every method for creating, listing, rotating and revoking a key
- CLI authentication is how
l4resolves a credential, and the read-write key its write commands need - Connecting a client covers the sign-in flow an assistant can use instead of a key
- Enterprise SSO (SAML) is signing in to the dashboard with your own identity provider