Authentication

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

Bearer Token (Recommended)

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

Open http://localhost:18080/management
Navigate to API Keys section
Click Add Key to generate new access keys
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!"}]
)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:18080/v1',
  apiKey: 'sk-test-123'  // Your configured access key
});

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

import "github.com/sashabaranov/go-openai"

client := openai.NewClient("sk-test-123")
client.BaseURL = "http://localhost:18080/v1"

resp, err := client.CreateChatCompletion(
    context.Background(),
    openai.ChatCompletionRequest{
        Model: "gemini-2.5-pro",
        Messages: []openai.ChatCompletionMessage{
            {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

Use Strong API Keys

Generate random keys with sufficient entropy:

openssl rand -hex 32

Prefix with sk- for consistency with OpenAI format.

Rotate Keys Regularly

Create new keys and deprecate old ones periodically. Use the Management Dashboard to manage active keys.

Restrict Remote Access

Only enable allow_remote: true when necessary. Use firewall rules to limit access to trusted IPs.

Monitor Usage

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:

Verify key is configured in config.yaml under access.keys
Check key is enabled: enabled: true
Ensure Authorization: Bearer <key> header is present

403 Forbidden

Cause: Remote access disabled or insufficient permissions Solution:

For remote access, set allow_remote: true in config
Verify key has required permissions for the endpoint
Check Management API secret is properly initialized

Next Steps

Chat Completions

Start sending authenticated requests

Management API

Configure advanced security settings

Overview

Endpoints

Provider Formats

Management API

Overview

Authentication Methods

Bearer Token (Recommended)

X-API-Key Header

Configuring Access Keys

Option 1: Configuration File

Option 2: Management Dashboard

Option 3: Environment Variable

SDK Configuration

Access Control

Key Permissions

Remote Access

Management API Authentication

Initialize Management Secret

WebSocket Authentication

Security Best Practices

Troubleshooting

401 Unauthorized

403 Forbidden

Next Steps

Chat Completions

Management API

​Overview

​Authentication Methods

​Bearer Token (Recommended)

​X-API-Key Header

​Configuring Access Keys

​Option 1: Configuration File

​Option 2: Management Dashboard

​Option 3: Environment Variable

​SDK Configuration

​Access Control

​Key Permissions

​Remote Access

​Management API Authentication

​Initialize Management Secret

​WebSocket Authentication

​Security Best Practices

​Troubleshooting

​401 Unauthorized

​403 Forbidden

​Next Steps

Chat Completions

Management API

Overview

Authentication Methods

Bearer Token (Recommended)

X-API-Key Header

Configuring Access Keys

Option 1: Configuration File

Option 2: Management Dashboard

Option 3: Environment Variable

SDK Configuration

Access Control

Key Permissions

Remote Access

Management API Authentication

Initialize Management Secret

WebSocket Authentication

Security Best Practices

Troubleshooting

401 Unauthorized

403 Forbidden

Next Steps