Overview
All RunAgent API requests require authentication using API keys. This guide covers how to obtain, use, and manage API keys securely.
Obtaining API Keys
Via CLI
# Setup authentication
runagent setup
# View current API key
runagent config show --key api_key
Via Dashboard
- Log in to dashboard.run-agent.ai
- Navigate to API Keys section
- Click “Create New Key”
- Copy and save securely
Using API Keys
Include your API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.run-agent.ai/v1/agents
SDK Authentication
# Python SDK
from runagent import RunAgentClient
client = RunAgentClient(
agent_id="agent-123",
api_key="YOUR_API_KEY"
)
Environment Variable
Set the API key as an environment variable:
export RUNAGENT_API_KEY="YOUR_API_KEY"
API Key Types
Personal Keys
- Tied to your user account
- Full access to your resources
- Should not be shared
Service Keys
- For production applications
- Limited scope and permissions
- Can be revoked independently
Temporary Keys
- Short-lived tokens
- For testing or demos
- Auto-expire after set time
Security Best Practices
Key Storage
Never commit API keys to version control or expose them in client-side code.
DO:
# Use environment variables
api_key = os.environ["RUNAGENT_API_KEY"]
# Or configuration files (gitignored)
with open(".secrets/api_key") as f:
api_key = f.read().strip()
DON’T:
# Never hardcode keys
api_key = "sk-abc123..." # WRONG!
Key Rotation
Regularly rotate your API keys:
# Generate new key
runagent keys create --name "production-2024"
# Update your application
export RUNAGENT_API_KEY="new-key"
# Revoke old key
runagent keys revoke "old-key-id"
Scope Limitation
Create keys with minimal required permissions:
# Read-only key
runagent keys create --scope read --name "monitoring"
# Agent-specific key
runagent keys create --agent-id agent-123 --name "agent-specific"
Request Signing
For additional security, enable request signing:
import hmac
import hashlib
import time
def sign_request(method, path, body, secret):
timestamp = str(int(time.time()))
message = f"{method}\n{path}\n{timestamp}\n{body}"
signature = hmac.new(
secret.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return {
"X-Signature": signature,
"X-Timestamp": timestamp
}
OAuth 2.0 (Coming Soon)
Future support for OAuth 2.0 flow:
# Authorization URL
auth_url = "https://auth.run-agent.ai/oauth/authorize"
params = {
"client_id": "your-client-id",
"redirect_uri": "https://yourapp.com/callback",
"response_type": "code",
"scope": "agents:read agents:write"
}
Rate Limiting
API keys have associated rate limits:
| Tier | Requests/Hour | Burst |
|---|
| Free | 100 | 10 |
| Pro | 1,000 | 100 |
| Enterprise | Custom | Custom |
Rate limit headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
IP Whitelisting
Restrict API key usage to specific IPs:
# Add IP to whitelist
runagent keys update <key-id> --add-ip 192.168.1.1
# List whitelisted IPs
runagent keys show <key-id>
Monitoring Key Usage
Via CLI
# View key usage
runagent keys usage <key-id>
# Set usage alerts
runagent keys alert <key-id> --threshold 80
Via API
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.run-agent.ai/v1/keys/usage
Error Responses
Invalid Key
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid",
"status": 401
}
}
Expired Key
{
"error": {
"code": "EXPIRED_API_KEY",
"message": "The API key has expired",
"status": 401
}
}
Rate Limited
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests",
"status": 429,
"retry_after": 3600
}
}
Troubleshooting
Key Not Working
- Check key format (should start with
ra_)
- Verify key hasn’t expired
- Ensure proper Authorization header format
- Check IP whitelist settings
- Verify rate limits haven’t been exceeded
Permission Denied
- Check key scope and permissions
- Verify resource ownership
- Ensure key is active
- Check organization settings
See Also
