Skip to main content

​
Overview

switchAILocal uses Bearer token authentication compatible with the OpenAI API format. Configure access keys in your config.yaml or use the Management Dashboard.

​
Authentication Methods

Include your API key in the Authorization header: 
curl http://localhost:18080/v1/chat/completions \
  -H "Authorization: Bearer sk-test-123" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-2.5-pro", "messages": [...]}'

​
X-API-Key Header

Alternative header format: 
curl http://localhost:18080/v1/models \
  -H "X-API-Key: sk-test-123"

​
Configuring Access Keys

​
Option 1: Configuration File

Add access keys to config.yaml:
config.yaml
access:
  keys:
    - key: sk-test-123
      name: "Development Key"
      enabled: true
    - key: sk-prod-456
      name: "Production Key"
      enabled: true

​
Option 2: Management Dashboard

  1. Open http://localhost:18080/management
  2. Navigate to API Keys section
  3. Click Add Key to generate new access keys
  4. Copy and use the generated key

​
Option 3: Environment Variable

Set a default key via environment variable: 
export SWITCHAI_ACCESS_KEY=sk-test-123
./switchAILocal

​
SDK Configuration

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:18080/v1",
    api_key="sk-test-123"  # Your configured access key
)

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

​
Access Control

​
Key Permissions

Each access key can be configured with specific permissions:
config.yaml
access:
  keys:
    - key: sk-readonly-789
      name: "Read-Only Key"
      permissions:
        - read:models
        - read:providers
      enabled: true
    - key: sk-admin-999
      name: "Admin Key"
      permissions:
        - "*"  # All permissions
      enabled: true

​
Remote Access

By default, the API only accepts requests from localhost. To enable remote access:
config.yaml
remote_management:
  allow_remote: true
  secret_key: "your-hashed-secret"  # Use Management API to set
Enabling remote access requires setting a strong secret key. Use the Management Dashboard to initialize security settings.

​
Management API Authentication

Management endpoints require a separate secret key: 
curl http://localhost:18080/v0/management/config \
  -H "X-Management-Key: your-secret-key"

​
Initialize Management Secret

curl -X POST http://localhost:18080/v0/management/initialize \
  -H "Content-Type: application/json" \
  -d '{
    "password": "your-secure-password"
  }'
See Management API for details.

​
WebSocket Authentication

WebSocket connections support query parameter authentication: 
const ws = new WebSocket(
  'ws://localhost:18080/v1/ws?apiKey=sk-test-123'
);
Alternatively, disable WebSocket auth in config.yaml:
config.yaml
websocket_auth: false  # Not recommended for production

​
Security Best Practices

Generate random keys with sufficient entropy:
openssl rand -hex 32
Prefix with sk- for consistency with OpenAI format.
Create new keys and deprecate old ones periodically. Use the Management Dashboard to manage active keys.
Only enable allow_remote: true when necessary. Use firewall rules to limit access to trusted IPs.
Check access logs in the Management Dashboard to detect unauthorized usage:
curl http://localhost:18080/v0/management/usage \
  -H "X-Management-Key: your-secret-key"

​
Troubleshooting

​
401 Unauthorized

Cause: Missing or invalid API key Solution:
  1. Verify key is configured in config.yaml under access.keys
  2. Check key is enabled: enabled: true
  3. Ensure Authorization: Bearer <key> header is present

​
403 Forbidden

Cause: Remote access disabled or insufficient permissions Solution:
  1. For remote access, set allow_remote: true in config
  2. Verify key has required permissions for the endpoint
  3. Check Management API secret is properly initialized

​
Next Steps

Chat Completions

Start sending authenticated requests

Management API

Configure advanced security settings