Authentication

Every request to the Levain Labs API is authenticated. You have two options: API keys for server-to-server traffic, and OAuth for interactive sessions in the dashboard.

API keys

Generate an API key from your dashboard settings. The key is shown once — store it somewhere safe.

Include it on every request as a bearer token:

curl https://api.levainlabs.com/api/v1/agents \
  -H "Authorization: Bearer $LEVAIN_API_KEY"

An X-API-Key header with the same value works too, if your HTTP client reserves the Authorization header for something else:

curl https://api.levainlabs.com/api/v1/agents \
  -H "X-API-Key: $LEVAIN_API_KEY"

Manage keys programmatically

You can also manage keys from the API itself:

• POST /api/v1/auth/api-keys — create a new key.
• GET /api/v1/auth/api-keys — list keys (the key value itself is never returned after creation).
• DELETE /api/v1/auth/api-keys/{key_id} — revoke a key. The revocation takes effect immediately.

Workspaces

Every resource in Levain belongs to a workspace. API keys are scoped to a single workspace; an agent, run, or sandbox created under one workspace is invisible to another. Call GET /api/v1/auth/workspace to see which workspace the current key belongs to, or GET /api/v1/auth/me for the full identity context (workspace, user, and how you authenticated).

Org API keys

Orgs with several workspaces — typically embedded-agents deployments running one workspace per end-customer — get a second kind of key. An org API key reaches every workspace in the org; pick the workspace per request with the X-Workspace-Id header:

curl https://api.levainlabs.com/api/v1/agents \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Org keys are created under Organization settings → API Keys or via the org API. Hand out workspace keys, never org keys, when a credential should stay confined to one workspace.

OAuth

The dashboard at platform.levainlabs.com supports login with Google and GitHub. OAuth sessions give humans access to the same resources a workspace API key would, with permissions tied to the workspace they're invited into.

Security practice

• Rotate keys periodically. Use the PATCH/DELETE endpoints above to manage them from your own infrastructure.
• Never check keys into source control. A secret scanner will find them before you do.
• Scope keys to a single environment where possible. Production keys and staging keys should be different keys, not the same key reused.
• Use short-lived keys for CI/CD pipelines when you can.