# 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.

```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.

| 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.             |
| `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. |

### 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](/docs/guides/create-api-key) for the complete
workspace setup and verification flow.