Authentication - Runtools.ai

API Keys

Use API keys for servers, scripts, CI jobs, and SDK clients. Keep them out of browser code and mobile clients. Create and rotate keys from Dashboard → Credentials → API Keys, the CLI, or the SDK:

runtools auth keys list
runtools auth keys create "ci-production" --scope "*"
runtools auth keys revoke <key-id>

// The full key value is returned ONCE, at creation — store it immediately.
const created = await rt.auth.createKey({
  name: 'ci-production',
  scopes: ['sandbox:*', 'agent:run'],
  expiresIn: '90d',
});
console.log(created.key); // rt_live_… (only present on the create response)

const keys = await rt.auth.listKeys();
await rt.auth.revokeKey(created.id);

API keys authenticate with X-API-Key:

curl https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

The SDK reads RUNTOOLS_API_KEY automatically:

import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools();
const sandboxes = await rt.sandbox.list();

Or pass a key explicitly:

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
});

Session Tokens

Dashboard and CLI login use WorkOS-backed session tokens. Session tokens authenticate with Authorization: Bearer:

curl https://api.runtools.ai/v1/me \
  -H "Authorization: Bearer $RUNTOOLS_ACCESS_TOKEN"

The CLI manages those tokens for you:

runtools login
runtools auth status
runtools logout

Environment Variables

.env

RUNTOOLS_API_KEY=rt_live_xxx

# Optional service overrides for local development
RUNTOOLS_API_URL=https://api.runtools.ai
RUNTOOLS_AUTH_URL=https://auth.runtools.ai
RUNTOOLS_TOOLS_URL=https://tools.runtools.ai
RUNTOOLS_BILLING_URL=https://billing.runtools.ai

Scopes

API key scopes are checked by the API service. Use the narrowest scopes that fit your integration.

Scope	Access
`*`	Full API key access for the organization
`sandbox:*`	Sandbox lifecycle and command execution
`agent:*`	Agent management and runs
`agent:run`	Run agents
`files:read`	Read workspace metadata and files
`files:write`	Create, update, and delete workspace metadata and files
`activity:read`	Read customer-visible activity events
`runmesh:read`	Read RunMesh nodes, configs, audit, and status
`runmesh:write`	Approve, rename, or revoke RunMesh devices
`tool:*`	Tool Hub installs, credentials, and execution
`ssh-key:*`	SSH key management

API keys are shown once at creation. Store them in a secret manager or environment variable, not in source code.

Rotation

Create a replacement key.
Deploy the new key to your application or CI secret store.
Verify the new key works.
Revoke the old key.

runtools auth keys create "production-2026-05" --scope "*"
runtools auth keys revoke <old-key-id>

Errors

Authentication failures use normal API error envelopes:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing authentication"
  }
}

If a request works in the dashboard but fails with an API key, check the key scopes and the organization selected when the key was created.

​API Keys

​Session Tokens

​Environment Variables

​Scopes

​Rotation

​Errors

API Keys

Session Tokens

Environment Variables

Scopes

Rotation

Errors