# Create an API key

Create a scoped key for Runtime API requests.

API keys are created per workspace. They are hashed at rest, and the plaintext secret is shown only once.

## In the app

### Open API Keys

In the workspace sidebar, open **API Keys**.

The page shows active and revoked keys, their mode, scopes, created time, and last-used time.

### Create a key

Click **Create API Key**.

Fill in:

| Field  | Notes                                                                               |
| ------ | ----------------------------------------------------------------------------------- |
| Label  | Optional human-readable name, max 80 characters.                                    |
| Mode   | `Live` or `Test`. Live keys start with `sk_live_`; test keys start with `sk_test_`. |
| Scopes | Select at least one scope.                                                          |

### Choose scopes

Common quickstart scopes:

* `run:write` — start, continue, steer, cancel, and delete runs
* `run:read` — retrieve runs, turns, and retained events
* `models:read` — list and inspect available models

Add more scopes only when needed:

* `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`, `env_vars:write`, `env_vars:reveal` — manage agent environment variables
* `api_keys:manage` — create, rotate, and revoke API keys through the API

### Copy the secret

After creation, Salambo opens a **Copy API Key** dialog.

Copy the secret before closing it. You cannot reveal it again.

## Runtime-capable scopes

Some scopes can create or access runtime execution data. Creating or rotating a key with these scopes checks runtime billing readiness:

* `run:write`
* `files:read`
* `files:write`
* `runs:write`

If the workspace billing owner is not runtime-ready, Salambo blocks creating or rotating a runtime-capable key and shows billing recovery guidance.

## Store the key locally

```bash
export SALAMBO_API_KEY="sk_live_..."
export SALAMBO_BASE_URL="https://YOUR_SALAMBO_BASE_URL"
```

Or in a project `.env` file that is ignored by Git:

```bash
SALAMBO_API_KEY=sk_live_...
SALAMBO_BASE_URL=https://YOUR_SALAMBO_BASE_URL
```

## Verify the key

A quick verification call uses `models:read`:

```bash
curl "$SALAMBO_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"
```

Expected shape:

```json
{
  "object": "list",
  "data": []
}
```

`data` contains active agent models for the workspace. An empty list means the key is valid but there are no active agents available to it.

## Revoke a key

Use the row menu on the API Keys page and choose **Revoke**. Revoked keys lose access immediately and remain visible in the revoked section for audit/history.