Salambo
Browse documentation
Core conceptsAPI keys

API keys

Authenticate API requests and control access with scopes.

View Markdown

API keys authenticate requests to Salambo API v1. Each key belongs to one workspace and has an explicit set of scopes.

bash
export SALAMBO_API_KEY="sk_..."

All API requests use bearer-token authentication:

http
Authorization: Bearer $SALAMBO_API_KEY

Key format

Every Salambo API key is a live key that starts with sk_live_. There is no separate test mode: use a separate test agent or workspace when you want to exercise your integration without touching production agents.

The key prefix is stored for display and lookup. The full secret is hashed at rest and shown only once when the key is created or rotated.

Scopes

Scopes determine what the key can do.

ScopeUse
models:readList available active agent models.
run:readRetrieve runs, turns, and retained events.
run:writeStart, continue, steer, cancel, and delete runs.
files:readRead run files and file content.
files:writeUpload input files.
agents:readList and inspect agents.
agents:writeCreate, update, archive, and run agents.
env_vars:readList environment variable metadata.
env_vars:writeCreate, update, and delete environment variables.
env_vars:revealReveal secret environment variable values.
api_keys:manageCreate, rotate, and revoke API keys through the API.

Scope rules

  • A scope that changes or reveals a resource needs its read scope: run:write needs run:read, files:write needs files:read, agents:write needs agents:read, and env_vars:write or env_vars:reveal need env_vars:read.
  • A key must grant at least one scope, and each scope only once.
  • Native Runs use run:read and run:write. The older plural runs:read and runs:write scopes no longer exist.

Runtime-capable scopes

Salambo treats these scopes as runtime-capable:

  • run:write
  • files:read
  • files:write

Creating or rotating a key with any of those scopes checks runtime billing readiness for the workspace billing owner. Configuration-only scopes can still be used for setup flows that do not start or access runtime execution.

Last used timestamp

When a key successfully authenticates, Salambo updates its last_used_at timestamp on a best-effort basis. A recently used key can show a recent last-used time even if the request later fails a runtime readiness check.

Security practices

  • Store API keys in environment variables or a secret manager.
  • Do not commit secrets to source control.
  • Use separate keys per environment and integration.
  • Give each key only the scopes it needs.
  • Revoke keys that are no longer used.

Continue with Create an API key for the complete workspace setup and verification flow.

PreviousWorkspaces and accounts
Up nextTroubleshooting