Authentication & Authorization

AgentRouter uses API keys for authentication and authorization. This document explains how to create, manage, and use API keys.

Authentication Methods

AgentRouter supports two HTTP header authentication methods:

1. Authorization Bearer Header

Authorization: Bearer sk-ar-your-api-key

This is the recommended method, compatible with OpenAI and Anthropic SDKs.

2. x-api-key Header

x-api-key: sk-ar-your-api-key

Alternative authentication method, may be more convenient for some clients.

API Key Format

All AgentRouter API keys follow a unified format:

sk-ar-xxxxxxxxxxxxxxxx

• sk- - Indicates this is a Secret Key
• ar- - Indicates this is an AgentRouter key
• xxxxxxxxxxxxxxxx - Randomly generated unique identifier

Creating API Keys

Via Web Console

1. Log in to AgentRouter
2. Go to the API Keys Management page
3. Click the "Create API Key" button
4. Configure key parameters:
   • Name (optional) - Friendly key name for identification
   • Request Limit (optional) - Maximum requests per time window
   • Reset Interval (optional) - Rate limit reset time (seconds)
5. Click "Create"
6. Important: Copy and save the key immediately - it will only be shown once!

Rate Limit Explanation

Rate limits control API call frequency:

• No limit - No rate limiting
• Requests + Interval - Example: 100 requests / 60 seconds = max 100 requests per minute
• Token bucket algorithm - When requests are exhausted, wait for the interval to automatically replenish

Examples:

Managing API Keys

Viewing Key List

On the API Keys Management page you can see:

• Key name
• Key prefix (e.g., sk-ar-abc...)
• Creation time
• Last used time
• Rate limit configuration
• Usage statistics

Deleting Keys

1. Find the key to delete in the key list
2. Click the "Delete" button
3. Confirm deletion

Note: After deletion, all requests using this key will fail immediately.

Metadata and Labels

API keys support storing metadata (JSON format):

{
  "environment": "production",
  "application": "my-app",
  "team": "engineering"
}

This helps you:

• Track key usage
• Categorize by project or team
• Audit and analyze

Using API Keys

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-ar-your-api-key",
    base_url="https://your-agentrouter.com/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Python (Anthropic SDK)

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ar-your-api-key",
    base_url="https://your-agentrouter.com"
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

curl

Using Authorization header:

curl https://your-agentrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-ar-your-api-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Using x-api-key header:

curl https://your-agentrouter.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-ar-your-api-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Environment Variable Configuration

Recommended: store API keys in environment variables:

Linux/macOS

export AGENTROUTER_API_KEY="sk-ar-your-api-key"
export AGENTROUTER_BASE_URL="https://your-agentrouter.com/v1"

Windows (PowerShell)

$env:AGENTROUTER_API_KEY="sk-ar-your-api-key"
$env:AGENTROUTER_BASE_URL="https://your-agentrouter.com/v1"

.env File

AGENTROUTER_API_KEY=sk-ar-your-api-key
AGENTROUTER_BASE_URL=https://your-agentrouter.com/v1

Load with python-dotenv:

from dotenv import load_dotenv
import os

load_dotenv()

api_key = os.getenv("AGENTROUTER_API_KEY")

Authentication Error Handling

401 Unauthorized

Causes:

• API key doesn't exist or has been deleted
• Incorrect API key format
• Missing authentication header

Solutions:

• Check if API key is correct
• Ensure key starts with sk-ar-
• Verify authentication header format

429 Too Many Requests

Cause:

• Exceeded API key rate limit

Response headers include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000

Solutions:

• Wait until X-RateLimit-Reset time and retry
• Implement exponential backoff retry
• Adjust request frequency
• Create a new API key

Security Best Practices

1. Don't Hardcode API Keys

❌ Wrong:

client = OpenAI(
    api_key="sk-ar-abc123...",  # Don't do this!
    base_url="https://your-agentrouter.com/v1"
)

✅ Correct:

import os
client = OpenAI(
    api_key=os.getenv("AGENTROUTER_API_KEY"),
    base_url=os.getenv("AGENTROUTER_BASE_URL")
)

2. Don't Commit to Version Control

Add to .gitignore:

.env
.env.local
*.key

3. Rotate Keys Regularly

Recommendations:

• Rotate keys every 90 days
• Keep old keys for a transition period
• Delete unused keys

4. Separate Keys by Environment

Create separate keys for different environments:

• Development - Low rate limits for testing
• Testing - Medium rate limits
• Production - High rate limits with strict monitoring

5. Use Metadata Tags

{
  "environment": "production",
  "created_by": "alice@company.com",
  "purpose": "mobile-app-backend",
  "version": "v2.0"
}

6. Monitor Unusual Usage

Regularly check for:

• Abnormally high request volumes
• Unexpected usage times
• High failure rates
• Access from unknown IP addresses

Account Authentication (Web Interface)

In addition to API keys, AgentRouter supports multiple ways to log in to the web console:

Email & Password

1. Register with email
2. Set a strong password (at least 8 characters with uppercase, lowercase, and numbers)
3. Verify email

OAuth Social Login

Supported providers:

• GitHub - Log in with GitHub account
• Google - Log in with Google account

Advantages:

• No need to remember passwords
• More secure authentication
• Quick registration and login

Session Management

• Session validity: 30 days
• Can log in on multiple devices
• Support for logging out all devices

Next Steps

• Getting Started - Create your first API key
• OpenAI Integration Guide - Use OpenAI SDK
• Anthropic Integration Guide - Use Anthropic SDK
• Troubleshooting - Solve authentication issues