Browse documentation

API keys

Authenticate API requests and control access with scopes.

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

export SALAMBO_API_KEY="sk_..."

All API requests use bearer-token authentication:

Authorization: Bearer $SALAMBO_API_KEY

Key format and modes

Mode	Prefix	Use
Live	`sk_live_`	Normal API access for a workspace.
Test	`sk_test_`	Test-mode API access where supported.

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.

Scope	Use
`models:read`	List available active agent models.
`run:read`	Retrieve runs, turns, and retained events.
`run:write`	Start, continue, steer, cancel, and delete runs.
`files:read`	Read run files and file content.
`files:write`	Upload input files.
`agents:read`	List and inspect agents.
`agents:write`	Create, update, archive, and run agents.
`runs:read`	List and inspect automation runs.
`runs:write`	Control run execution.
`env_vars:read`	List environment variable metadata.
`env_vars:write`	Create, update, and delete environment variables.
`env_vars:reveal`	Reveal secret environment variable values.
`api_keys:manage`	Create, rotate, and revoke API keys through the API.

Runtime-capable scopes

Salambo treats these scopes as runtime-capable:

run:write
files:read
files:write
runs: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