API Key Rotation

Regular API key rotation limits the blast radius of a compromised key and satisfies many security compliance requirements. ARouter’s key management API supports zero-downtime rotation.

Rotation Strategy

The safest rotation pattern is create-then-delete:

Create a new key with the same permissions as the old one
Deploy the new key to your application
Verify the new key is working
Delete the old key

This ensures no downtime — traffic continues on the old key until the new key is confirmed working.

Step 1: Create a New Key

Use the Key Management API to create a replacement key:

cURL
Python
TypeScript

curl -X POST https://api.arouter.ai/v1/keys \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-v2",
    "allowed_providers": ["openai", "anthropic", "google"],
    "spending_limit": 500.00
  }'

import requests

response = requests.post(
    "https://api.arouter.ai/v1/keys",
    headers={"Authorization": "Bearer lr_live_xxxx"},
    json={
        "name": "production-v2",
        "allowed_providers": ["openai", "anthropic", "google"],
        "spending_limit": 500.00,
    },
)
new_key = response.json()["key"]
print(f"New key created: {new_key[:8]}...")

const response = await fetch("https://api.arouter.ai/v1/keys", {
  method: "POST",
  headers: {
    Authorization: "Bearer lr_live_xxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "production-v2",
    allowed_providers: ["openai", "anthropic", "google"],
    spending_limit: 500.0,
  }),
});

const { key } = await response.json();
console.log(`New key: ${key.substring(0, 8)}...`);

Save the returned key value immediately — ARouter only returns the full key once at creation time.

Step 2: Update Your Application

Update the AROUTER_API_KEY environment variable (or equivalent secret) in your deployment environment:

# Example with a .env file
AROUTER_API_KEY=lr_live_new_key_here

# Example updating a Kubernetes secret
kubectl create secret generic arouter-credentials \
  --from-literal=api-key=lr_live_new_key_here \
  --dry-run=client -o yaml | kubectl apply -f -

Redeploy or restart your application to pick up the new key.

Step 3: Verify the New Key

Before deleting the old key, confirm the new key is working:

cURL
Python

curl https://api.arouter.ai/v1/models \
  -H "Authorization: Bearer lr_live_new_key_here"

from openai import OpenAI

# Test with new key
client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_new_key_here",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=5,
)
print("New key verified:", response.choices[0].message.content)

Check the ARouter Dashboard to confirm requests are appearing under the new key.

Step 4: Delete the Old Key

Once the new key is confirmed working, delete the old one using its key ID:

cURL
Python

curl -X DELETE https://api.arouter.ai/v1/keys/key_oldid \
  -H "Authorization: Bearer lr_live_new_key_here"

import requests

requests.delete(
    "https://api.arouter.ai/v1/keys/key_oldid",
    headers={"Authorization": "Bearer lr_live_new_key_here"},
)
print("Old key deleted")

Automated Rotation

For high-security environments, automate rotation on a schedule using your CI/CD system or a secrets manager:

GitHub Actions Example

name: Rotate ARouter Key

on:
  schedule:
    - cron: '0 0 1 * *'  # Monthly

jobs:
  rotate:
    runs-on: ubuntu-latest
    steps:
      - name: Create new key
        id: create
        run: |
          NEW_KEY=$(curl -s -X POST https://api.arouter.ai/v1/keys \
            -H "Authorization: Bearer ${{ secrets.AROUTER_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"name": "production-auto-rotated"}' \
            | jq -r .key)
          echo "new_key=$NEW_KEY" >> $GITHUB_OUTPUT

      - name: Update secret
        uses: gliech/create-github-secret-action@v1
        with:
          name: AROUTER_API_KEY
          value: ${{ steps.create.outputs.new_key }}
          token: ${{ secrets.GH_TOKEN }}

Listing Active Keys

List all active keys to audit what’s in use:

curl https://api.arouter.ai/v1/keys \
  -H "Authorization: Bearer lr_live_xxxx"

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-v2",
      "created_at": "2025-01-15T10:00:00Z",
      "last_used_at": "2025-04-01T08:30:00Z",
      "spending_limit": 500.00
    },
    {
      "id": "key_def456",
      "name": "staging",
      "created_at": "2025-03-01T09:00:00Z",
      "last_used_at": "2025-04-01T07:15:00Z",
      "spending_limit": 50.00
    }
  ]
}

Best Practices

Rotate on a schedule — Monthly rotation is a good baseline for most applications
Rotate immediately after suspected compromise — Do not wait for the next scheduled rotation
Use descriptive names — Include version or date in key names (production-2025-04, production-v3)
Set spending limits — Always configure spending_limit on production keys to cap exposure
Use separate keys per environment — Never share a key between production and staging
Audit regularly — Review the key list monthly and delete any keys that are no longer in use
Store keys in secrets managers — Use AWS Secrets Manager, HashiCorp Vault, or equivalent rather than .env files in version control

See Key Management for the full key management guide, and the Key Management API for the complete API reference.

Documentation Index

​Rotation Strategy

​Step 1: Create a New Key

​Step 2: Update Your Application

​Step 3: Verify the New Key

​Step 4: Delete the Old Key

​Automated Rotation

​GitHub Actions Example

​Listing Active Keys

​Best Practices