API Keys
AgentWarden uses API keys to authenticate requests. Each organization has a unique API key that grants full access to that organization’s resources.
Getting Your API Key
Navigate to Settings
Click Settings in the left sidebar
View General Tab
In the General tab, you’ll find your API key
Copy API Key
Click the Copy button to copy your API key
ak_1234567890abcdefghijklmnopqrstuvwxyz
- Prefix:
ak_ (production) or test_ (test mode)
- Length: 40 characters total
- Characters: Alphanumeric (a-z, 0-9)
Using API Keys
In Python SDK
from agentwarden import AgentWarden
# Direct initialization
guard = AgentWarden(api_key="ak_1234567890abcdefghijklmnopqrstuvwxyz")
Via Environment Variable
The recommended approach for production:
# .env file
AGENTWARDEN_API_KEY=ak_1234567890abcdefghijklmnopqrstuvwxyz
import os
from agentwarden import AgentWarden
# Reads from AGENTWARDEN_API_KEY environment variable
guard = AgentWarden(api_key=os.getenv('AGENTWARDEN_API_KEY'))
Direct API Calls
When calling the API directly (without SDK):
curl https://api.agentwarden.io/sdk/check \
-H "X-API-Key: ak_1234567890abcdefghijklmnopqrstuvwxyz" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "support-bot",
"action": "stripe.refund",
"context": {"amount": 50}
}'
SDK endpoints use the X-API-Key header, while dashboard/management API uses JWT tokens with Authorization: Bearer header.
Security Best Practices
1. Never Commit API Keys to Version Control
❌ Bad:
# config.py - NEVER DO THIS!
API_KEY = "ak_1234567890abcdefghijklmnopqrstuvwxyz"
# config.py
import os
API_KEY = os.getenv('AGENTWARDEN_API_KEY')
# .env (add to .gitignore!)
AGENTWARDEN_API_KEY=ak_1234567890abcdefghijklmnopqrstuvwxyz
# .gitignore
.env
.env.*
2. Use Environment-Specific Keys
Use different API keys for different environments:
# .env.development
AGENTWARDEN_API_KEY=test_dev_key_here
# .env.staging
AGENTWARDEN_API_KEY=test_staging_key_here
# .env.production
AGENTWARDEN_API_KEY=ak_production_key_here
3. Never Expose API Keys in Client-Side Code
❌ Never do this:
// frontend.js - NEVER EXPOSE API KEY IN BROWSER!
const guard = new AgentWarden('ak_1234567890...');
# backend.py - API key only on server
from flask import Flask, request
from agentwarden import AgentWarden
app = Flask(__name__)
guard = AgentWarden(api_key=os.getenv('AGENTWARDEN_API_KEY'))
@app.route('/check-permission', methods=['POST'])
def check_permission():
data = request.json
result = guard.check(
agent_id=data['agent_id'],
action=data['action'],
context=data['context']
)
return {'allowed': result.allowed}
4. Rotate Keys Regularly
Rotate your API keys periodically (every 90 days recommended):
Generate New Key
In Settings → General, click Regenerate API Key
Update Environment Variables
Update your production environment with the new key
Deploy
Deploy the updated configuration
Verify
Confirm the new key works before the old one expires
Regenerating your API key immediately invalidates the old one. All services using the old key will stop working until updated.
5. Use Secrets Management
For production, use a secrets management service:
AWS Secrets Manager
HashiCorp Vault
Google Secret Manager
Azure Key Vault
import boto3
from botocore.exceptions import ClientError
def get_api_key():
secret_name = "agentwarden/api-key"
region_name = "us-east-1"
session = boto3.session.Session()
client = session.client(
service_name='secretsmanager',
region_name=region_name
)
try:
response = client.get_secret_value(SecretId=secret_name)
return response['SecretString']
except ClientError as e:
raise e
# Usage
from agentwarden import AgentWarden
guard = AgentWarden(api_key=get_api_key())
import hvac
def get_api_key():
client = hvac.Client(url='http://127.0.0.1:8200')
client.token = os.getenv('VAULT_TOKEN')
secret = client.secrets.kv.v2.read_secret_version(
path='agentwarden/api-key'
)
return secret['data']['data']['key']
# Usage
from agentwarden import AgentWarden
guard = AgentWarden(api_key=get_api_key())
from google.cloud import secretmanager
def get_api_key():
client = secretmanager.SecretManagerServiceClient()
name = f"projects/{project_id}/secrets/agentwarden-api-key/versions/latest"
response = client.access_secret_version(request={"name": name})
return response.payload.data.decode('UTF-8')
# Usage
from agentwarden import AgentWarden
guard = AgentWarden(api_key=get_api_key())
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
def get_api_key():
credential = DefaultAzureCredential()
vault_url = "https://your-vault.vault.azure.net"
client = SecretClient(vault_url=vault_url, credential=credential)
secret = client.get_secret("agentwarden-api-key")
return secret.value
# Usage
from agentwarden import AgentWarden
guard = AgentWarden(api_key=get_api_key())
6. Limit API Key Scope (Coming Soon)
In the future, you’ll be able to create scoped API keys with limited permissions:
# Coming soon - scoped keys
guard = AgentWarden(api_key="ak_readonly_1234...") # Read-only
guard = AgentWarden(api_key="ak_agent_bot1_5678...") # Single agent only
Test vs Production Keys
Test Keys
Test keys are prefixed with test_ and can be used for:
- Development environments
- CI/CD pipelines
- Integration testing
- Sandbox environments
Benefits:
- Don’t count against plan limits
- Can be safely shared with developers
- Isolated from production data
# Development
guard = AgentWarden(api_key="test_dev_1234567890...")
Production Keys
Production keys are prefixed with ak_ and should be:
- Used only in production
- Stored securely
- Rotated regularly
- Never committed to code
# Production
guard = AgentWarden(api_key=os.getenv('AGENTWARDEN_API_KEY'))
Authentication Errors
Invalid API Key
try:
guard = AgentWarden(api_key="invalid_key")
result = guard.check("agent-id", "action")
except AuthenticationError:
print("Invalid API key - check your configuration")
{
"detail": "Invalid API key"
}
401 Unauthorized
Missing API Key
curl https://api.agentwarden.io/sdk/check \
-H "Content-Type: application/json" \
-d '{"agent_id": "bot", "action": "test"}'
{
"detail": "Missing API key"
}
401 Unauthorized
Inactive Organization
If your organization is deactivated (e.g., expired trial, payment failed):
HTTP Response:
{
"detail": "Organization is not active"
}
401 Unauthorized
Rate Limiting
API keys are subject to rate limits based on your plan:
| Plan | Rate Limit |
|---|
| Free | 100 requests/minute |
| Pro | 1,000 requests/minute |
| Business | 10,000 requests/minute |
| Enterprise | Custom |
Handling Rate Limits
from agentwarden import AgentWarden, RateLimitError
import time
guard = AgentWarden(api_key="your-key")
def check_with_retry(agent_id, action, context, max_retries=3):
for attempt in range(max_retries):
try:
return guard.check(agent_id, action, context)
except RateLimitError as e:
if attempt < max_retries - 1:
# Exponential backoff
wait_time = (2 ** attempt) * 1
print(f"Rate limited. Retrying in {wait_time}s...")
time.sleep(wait_time)
else:
raise
return None
# Usage
result = check_with_retry("agent-id", "action", {"amount": 50})
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000
IP Whitelisting (Enterprise)
Enterprise customers can whitelist specific IP addresses:
Provide IPs
List all IPs that will access the API
Configuration
We’ll configure IP whitelisting for your organization
Test
Verify access from allowed IPs
IP whitelisting is available on Enterprise plans only. Contact sales JWT Tokens (Dashboard API)
For accessing the dashboard API programmatically, use JWT tokens:
Getting a JWT Token
curl -X POST https://api.agentwarden.io/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"password": "your-password"
}'
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Using JWT Tokens
curl https://api.agentwarden.io/api/agents \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json"
JWT tokens are for dashboard/management API only. For SDK operations (check, log), always use API keys.
Security Checklist
Troubleshooting
- Verify API key is correct (copy from dashboard)
- Check for extra spaces or characters
- Ensure API key is not expired/regenerated
- Verify organization is active
- Implement exponential backoff
- Cache permission checks when appropriate
- Upgrade plan for higher limits
- Contact support for burst capacity
API key not working in production
- Check environment variables are set correctly
- Verify secrets manager configuration
- Ensure production uses production key (not test key)
- Check for typos in environment variable names
- Only organization admins can regenerate keys
- Contact your admin if you need a new key
- Or request admin access from your team
Next Steps
