Authentication

Overview

TokenRouter uses API keys for authentication. All API requests must include a valid API key in the Authorization header as a Bearer token.

Creating an API Key

1. Sign up or log in at tokenrouter.io
2. Navigate to Console → API Keys
3. Click Create API Key
4. Give your key a descriptive name (e.g., “Production”, “Development”, “Staging”)
5. Copy the API key immediately - it will only be shown once

Caution

API keys are only displayed once during creation. Store them securely in your environment variables or secrets manager. If you lose an API key, you’ll need to create a new one.

Using API Keys

Include your API key in the Authorization header of every request:

TypeScript

import Tokenrouter from 'tokenrouter';

const client = new Tokenrouter({
  apiKey: process.env.TOKENROUTER_API_KEY, // tr_...
});

const response = await client.responses.create({
  model: 'auto:balance',
  input: 'Hello, world!'
});

Python

import os
from tokenrouter import Tokenrouter

client = Tokenrouter(
    api_key=os.environ.get("TOKENROUTER_API_KEY"),  # tr_...
)

response = client.responses.create(
    model="auto:balance",
    input="Hello, world!"
)

cURL

curl https://api.tokenrouter.io/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_your_api_key_here" \
  -d '{
    "model": "auto:balance",
    "input": "Hello, world!"
  }'

API Key Format

TokenRouter API keys follow this format:

• Prefix: tr_
• Example: tr_1234567890abcdef1234567890abcdef

Environment Variables

Store your API key in environment variables to keep it secure:

Node.js (.env)

# .env file
TOKENROUTER_API_KEY=tr_1234567890abcdef1234567890abcdef

Load with a package like dotenv:

import 'dotenv/config';
import Tokenrouter from 'tokenrouter';

const client = new Tokenrouter({
  apiKey: process.env.TOKENROUTER_API_KEY
});

Python

# .env file
TOKENROUTER_API_KEY=tr_1234567890abcdef1234567890abcdef

Load with python-dotenv:

from dotenv import load_dotenv
import os
from tokenrouter import Tokenrouter

load_dotenv()

client = Tokenrouter(
    api_key=os.getenv("TOKENROUTER_API_KEY")
)

Shell

# Export in your shell
export TOKENROUTER_API_KEY=tr_1234567890abcdef1234567890abcdef

# Or add to .bashrc / .zshrc
echo 'export TOKENROUTER_API_KEY=tr_...' >> ~/.bashrc

Tip

Never commit API keys to version control. Add .env to your .gitignore file.

Key Permissions and Scope

API keys inherit your workspace settings including:

• Quota Limits: Monthly token limits and rate limits
• Firewall Rules: Content filtering and security policies
• Routing Rules: Custom routing logic and preferences
• Provider Access: Which providers you have configured

Security Best Practices

1. Rotate Keys Regularly

Create new API keys and delete old ones periodically (e.g., every 90 days).

2. Use Environment-Specific Keys

Create separate keys for development, staging, and production:

tr_dev_...     # Development
tr_staging_... # Staging
tr_prod_...    # Production

3. Limit Key Exposure

• Never log API keys
• Never expose keys in client-side code
• Use server-side proxy for browser applications
• Store keys in secure secret managers (AWS Secrets Manager, HashiCorp Vault, etc.)

4. Monitor Usage

Check the Logs view regularly to:

• Detect unusual usage patterns
• Identify potentially compromised keys
• Track which keys are being used

Revoking API Keys

If an API key is compromised:

1. Go to Console → API Keys
2. Find the compromised key
3. Click Delete or Revoke
4. Create a new key
5. Update your application with the new key

Revoked keys will immediately stop working for all requests.

Request Metadata

All authenticated requests automatically include:

• Request ID: Unique identifier for each request
• Idempotency Key: Prevents duplicate requests
• Latency Telemetry: Response time tracking
• User Agent: SDK version and platform information

You can view this metadata in the Console → Logs view.

HTTPS Required

Danger

All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected.

TokenRouter enforces TLS 1.2 or higher for all connections.

Error Responses

If authentication fails, you’ll receive one of these error responses:

Missing API Key

{
  "error": {
    "type": "authentication_error",
    "message": "No API key provided. Include your API key in the Authorization header.",
    "http_status": 401
  }
}

Invalid API Key

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "http_status": 401
  }
}

Revoked API Key

{
  "error": {
    "type": "authentication_error",
    "message": "API key has been revoked",
    "http_status": 401
  }
}

Next Steps

After setting up authentication:

1. Add Provider Keys - Configure your AI provider credentials
2. Quickstart Guide - Make your first request
3. API Reference - Explore all available endpoints