Authentication

Overview

AI Gateway uses bearer token authentication with gateway API keys. Keys are prefixed with gw_sk_ to distinguish them from provider keys.

Gateway API Keys

Key Format

Gateway API keys follow this format:

gw_sk_[random-string]

Example: gw_sk_XwmWjL8x9aBcDeFgHiJkLmNo

Creating Keys

1. Navigate to AI Gateway Settings
2. Under "Gateway API Keys", click Create API Key
3. Enter a name (e.g., "Production", "Development")
4. Click Create
5. Copy the key immediately (it won't be shown again)

Key Permissions

All gateway keys have full access to:

• Chat completions endpoint
• Models endpoint
• Your configured providers

Coming soon: Scoped keys with limited permissions.

Using Your API Key

Authorization Header

Include your key in the Authorization header:

curl -X POST https://api.transactional.dev/ai/v1/chat/completions \
  -H "Authorization: Bearer gw_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}]}'

With OpenAI SDK

import OpenAI from 'openai';
 
const openai = new OpenAI({
  baseURL: 'https://api.transactional.dev/ai/v1',
  apiKey: 'gw_sk_your_key_here',  // Gateway key, not OpenAI key
});

With Python

from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.transactional.dev/ai/v1",
    api_key="gw_sk_your_key_here"
)

Environment Variables

Store keys securely in environment variables:

# .env
GATEWAY_API_KEY=gw_sk_your_key_here

const openai = new OpenAI({
  baseURL: 'https://api.transactional.dev/ai/v1',
  apiKey: process.env.GATEWAY_API_KEY,
});

Framework Examples

Next.js:

# .env.local
GATEWAY_API_KEY=gw_sk_your_key_here

Vercel:

vercel env add GATEWAY_API_KEY

Docker:

services:
  app:
    environment:
      - GATEWAY_API_KEY=${GATEWAY_API_KEY}

Key Management

Viewing Keys

1. Go to AI Gateway > Settings
2. Under "Gateway API Keys", see all your keys
3. View name, creation date, and last used time

Revoking Keys

1. Find the key in the list
2. Click the ... menu
3. Select Revoke
4. Confirm revocation

Warning: Revoking a key immediately invalidates it. Any applications using that key will fail.

Key Rotation

Best practice is to rotate keys periodically:

1. Create a new key
2. Update your applications to use the new key
3. Monitor for any remaining usage of the old key
4. Revoke the old key

Security Best Practices

Do

• Store keys in environment variables
• Use different keys for development and production
• Rotate keys regularly (every 90 days recommended)
• Monitor key usage in the dashboard
• Revoke unused keys

Don't

• Commit keys to version control
• Share keys between applications
• Expose keys in client-side code
• Log keys in application logs

Compromised Keys

If a key is exposed:

1. Immediately revoke the key in the dashboard
2. Create a new key
3. Update all applications using the old key
4. Review access logs for unauthorized usage

Error Responses

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Causes:

• Missing Authorization header
• Invalid key format
• Key doesn't exist
• Key has been revoked

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have access to this resource"
  }
}

Causes:

• Key doesn't have permission for this endpoint
• Organization doesn't have access to this feature

Rate Limits

Each API key has its own rate limits:

Set custom per-key limits in the dashboard.

Next Steps

• Chat Completions API
• Models API
• Error Handling