SDK
Authentication & scopes
The SDK authenticates with a RunBerth API key (mk_…). It lives on your server and never touches a browser.
Get a key
Mint one from the dashboard (Settings → API keys) or with runberth keys create. Set it as RUNBERTH_API_KEY and both SDKs pick it up automatically.


Scopes
Every key carries scopes. Hand a subsystem the narrowest key it needs. A leaked key can then only do what its scope allows. manage covers the ordinary API. Fleet requires explicit permission.
| Scope | Grants |
|---|---|
| provision | create agents |
| deploy | start / stop / restart / sleep / chat |
| secrets | read / write env vars |
| manage | ordinary API access, including delete and key management; Fleet requires its own permission |
| fleet | Fleet API (preview); returns a fleet ID with the key; cannot be restricted to one project |
| computers | the Computers product (MCP and /api/v1/computers); a key with only this scope reaches nothing else, and manage or full access reach Computers too |
| sandboxes | Sandboxes (create, run, snapshots, secrets, sandbox webhooks); manage reaches them too. Starting a swarm needs provision |
Mint a scoped key
A background worker that only chats to existing agents needs deploy, not provision, secrets, or manage. Minting keys itself requires a manage key.
Without scopes a key gets provision, deploy, secrets and manage; computers and sandboxes are never added for you (manage already covers them). Pass projectId (project_id in Python) to tie a key to one project: it then works only on that project's front door and usage routes and is refused everywhere else. Use it for a per-tenant or partner-facing service.
const worker = await runberth.keys.create({
name: 'chat-worker',
scopes: ['deploy'], // chat/start/stop only
})
// worker.rawKey is shown once. Hand it to the worker as RUNBERTH_API_KEY.
const tenant = await runberth.keys.create({ name: 'tenant-a', projectId: agent.projectId })Fleet API (preview)
Create a Fleet key in Settings → API keys. Open Advanced and select Fleet (preview). Clear the other permissions if this key only needs the Fleet API. Leave the project set to the whole account. Copy the key when it appears and copy its Fleet ID. You can copy the fleet ID again from the key list. No separate enablement request is needed.
The key creation response includes raw_key and fleet_id. A Fleet-only key authenticates requests under /v1/fleets/{fleet_id}; it cannot manage account keys or replace a key used by the ordinary CLI. You can combine Fleet with ordinary permissions. Existing nova keys keep working with their bound fleet ID. The account's normal billing and usage limits apply.
export RUNBERTH_FLEET_KEY='your-key'
export RUNBERTH_FLEET_ID='your-fleet-id'
curl "https://api.runberth.com/v1/fleets/$RUNBERTH_FLEET_ID/agents" \
-H "Authorization: Bearer $RUNBERTH_FLEET_KEY"Fleet is a preview. Use non-critical workloads while end-to-end verification of recovery, bundle application, rollouts and erasure continues. Endpoint availability is not a claim that every failure and recovery path has completed qualification.
Per-sandbox keys
To let code inside or next to one sandbox drive only that sandbox, mint a per-sandbox key (msk_…) with keys.create({ sandbox }). It lasts one day by default (60 seconds to 30 days) and its secret is returned once.
const key = await runberth.keys.create({ sandbox: sandbox.id, ttlSeconds: 3600 })
// key.secret is shown once.mk_ keys, so restricted keys are genuinely restricted.