Skip to main content

​
API Keys

All API requests require authentication using an API key.

​
Creating an API Key

  1. Go to Dashboard → API Keys
  2. Click Create New Key
  3. Give it a name (e.g., “Production”, “Development”)
  4. Copy the key - it will only be shown once!
Keep your API key secure. Never expose it in client-side code or commit it to version control.

​
Key Types

PrefixTypeUse Case
rt_live_ProductionProduction applications
rt_test_TestDevelopment and testing
Test keys have reduced rate limits but don’t incur charges.

​
Using Your API Key

​
HTTP Header

Include your API key in the X-API-Key header: 
curl https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: rt_live_xxx"

​
SDK

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

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

​
CLI

runtools auth set-key rt_live_xxx

​
Environment Variables

Store your API key in environment variables:
.env
RUNTOOLS_API_KEY=rt_live_xxx

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

​
Scopes

API keys can have restricted scopes:
ScopePermissions
*Full access (default)
sandboxesCreate, read, update, delete sandboxes
sandboxes:readRead-only sandbox access
agentsRun agents
toolsExecute tools
templatesManage templates
Create scoped keys in the dashboard: 
[x] sandboxes
[x] agents
[ ] tools
[ ] templates

​
Rate Limits

Each API key has rate limits based on your plan:
TierRequests/MinuteConcurrent
Free605
Pro30020
Team1,000100
EnterpriseCustomCustom
Rate limit headers are included in every response: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1609459200

​
Handling Rate Limits

import { RateLimitError } from '@runtools/sdk';

try {
  await rt.sandboxes.create({ template: 'nodejs-20' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
    await sleep(error.retryAfter);
    // Retry...
  }
}

​
Key Rotation

Rotate keys regularly for security:
  1. Create a new key in the dashboard
  2. Update your applications to use the new key
  3. Verify the new key works
  4. Delete the old key

​
Security Best Practices

Never hardcode API keys. Use environment variables or secret managers.
Create keys with only the permissions they need.
Rotate keys periodically, especially after team changes.
Check the dashboard for unusual API activity.
Don’t use production keys during development.