Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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 or with the CLI: 
runtools auth keys list
runtools auth keys create "ci-production" --scopes "*"
runtools auth keys revoke <key-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/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_CONVEX_URL=https://confident-oyster-531.convex.cloud

​
Scopes

API key scopes are checked by the API service. Use the narrowest scopes that fit your integration.
ScopeAccess
*Full API key access for the organization
sandbox:*Sandbox lifecycle and command execution
agent:*Agent management and runs
agent:runRun agents and workflows
workflow:*Workflow management, runs, triggers, and versions
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

  1. Create a replacement key.
  2. Deploy the new key to your application or CI secret store.
  3. Verify the new key works.
  4. Revoke the old key.
runtools auth keys create "production-2026-05" --scopes "*"
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.