Security Configuration

API Key Authentication

switchAILocal requires clients to authenticate using API keys. Requests must include the Authorization: Bearer <key> header.

Configuring API Keys

config.yaml

api-keys:
  - "sk-test-123"
  - "sk-prod-456"

array

required

List of valid API keys for client authentication. All requests to /v1/* endpoints require a key from this list.

Example client request:

curl https://localhost:18080/v1/chat/completions \
  -H "Authorization: Bearer sk-test-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-pro",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Store API keys securely. Do not commit them to version control. Use environment-based configuration for production deployments.

Key Rotation

API keys support hot reload. To rotate keys:

Add new key to api-keys list
Save config.yaml
switchAILocal automatically reloads (no restart needed)
Update clients to use new key
Remove old key from config

api-keys:
  - "sk-old-key-123"     # Keep temporarily during migration
  - "sk-new-key-456"     # New key for clients

Management Access Control

The Management API provides dashboard access and control endpoints. It has separate authentication and access controls.

config.yaml

remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: false
  panel-github-repository: "https://github.com/traylinx/switchAILocal-Management-Center"

Management Secret Key

string

Management authentication key. All management requests require this key. Leave empty to disable Management API entirely (404 for all management routes).

Automatic hashing: When you set a plaintext key:

remote-management:
  secret-key: "my-secure-password"

switchAILocal automatically hashes it with bcrypt on first startup:

remote-management:
  secret-key: "$2a$10$...<bcrypt-hash>..."

The hashed value is persisted back to config.yaml automatically. Future startups skip re-hashing.

Remote Access Control

boolean

default:"false"

Allow remote (non-localhost) access to management endpoints. When false, only localhost (127.0.0.1, ::1) can access management routes, even with valid key.

Localhost-only (default):

remote-management:
  allow-remote: false
  secret-key: "your-management-key"

✅ Requests from 127.0.0.1 with valid key → Allowed
❌ Requests from 192.168.1.100 with valid key → Denied (403)

Remote access enabled:

remote-management:
  allow-remote: true
  secret-key: "your-management-key"

✅ Requests from any IP with valid key → Allowed

Enabling allow-remote: true exposes management endpoints to the network. Ensure you use a strong secret key and TLS.

Management Control Panel

boolean

default:"false"

Disable the bundled management control panel asset download and HTTP route. When true, management UI is not served.

string

GitHub repository URL for management panel assets. Override to use custom dashboard.

Disable dashboard UI:

remote-management:
  secret-key: "api-only"
  disable-control-panel: true  # API access only, no UI

Disabling Management API

To completely disable all management endpoints:

remote-management:
  secret-key: ""  # Empty = Management API disabled (404)

With empty secret key:

Management dashboard returns 404
All /api/management/* routes return 404
Client API (/v1/*) continues working normally

WebSocket Authentication

Control authentication for WebSocket API:

config.yaml

ws-auth: true

boolean

default:"true"

Enable authentication for WebSocket API (/v1/ws). Requires same API keys as REST endpoints.

Disabling WebSocket authentication (ws-auth: false) allows unauthenticated access to streaming endpoints. Only disable in trusted environments.

TLS/HTTPS Configuration

Enable HTTPS for encrypted transport:

config.yaml

tls:
  enable: false
  cert: ""
  key: ""

boolean

default:"false"

Enable HTTPS server mode with TLS certificates

string

Path to TLS certificate file (PEM format)

string

Path to TLS private key file (PEM format)

Production TLS Example

With Let’s Encrypt:

host: ""
port: 443

tls:
  enable: true
  cert: "/etc/letsencrypt/live/api.example.com/fullchain.pem"
  key: "/etc/letsencrypt/live/api.example.com/privkey.pem"

remote-management:
  allow-remote: true
  secret-key: "<strong-password>"

api-keys:
  - "sk-prod-..."

With custom CA:

tls:
  enable: true
  cert: "/etc/ssl/certs/switchai.crt"
  key: "/etc/ssl/private/switchai.key"

TLS certificate changes require a server restart. Hot reload does not apply to TLS settings.

Authentication Directory

Configure storage location for authentication tokens:

config.yaml

auth-dir: "~/.switchailocal"

string

default:"~/.switchailocal"

Directory for OAuth tokens, session data, and authentication cache. Supports ~ for home directory.

This directory contains:

tokens.json - OAuth refresh tokens (Gemini, etc.)
Session state for authenticated providers
Authentication cache

Ensure this directory has restricted permissions (chmod 700) to prevent token theft.

Security Best Practices

1. Use Strong API Keys

# ❌ Weak keys
api-keys:
  - "test"
  - "123456"

# ✅ Strong keys
api-keys:
  - "sk-4f8a9b2c...32-char-random"
  - "sk-7d3e1f9a...32-char-random"

Generate strong keys:

openssl rand -base64 32

2. Enable TLS in Production

# ✅ Production configuration
tls:
  enable: true
  cert: "/path/to/cert.pem"
  key: "/path/to/key.pem"

3. Restrict Management Access

# ✅ Secure management (localhost only)
remote-management:
  allow-remote: false
  secret-key: "<strong-unique-password>"

# ⚠️ Remote access (ensure TLS + strong key)
remote-management:
  allow-remote: true
  secret-key: "<very-strong-password>"

4. Secure Authentication Directory

# Set restrictive permissions
chmod 700 ~/.switchailocal
chmod 600 ~/.switchailocal/tokens.json

5. Rotate Keys Regularly

Set up a key rotation schedule:

Client API keys: Rotate every 90 days
Management secret key: Rotate every 180 days
OAuth tokens: Automatically refreshed by switchAILocal

6. Use Environment-Specific Configs

# config.production.yaml
api-keys:
  - "${API_KEY_1}"  # Load from environment
  - "${API_KEY_2}"

remote-management:
  secret-key: "${MGMT_SECRET}"

Firewall Configuration

When deploying with allow-remote: true, configure firewall rules:

# Allow HTTPS traffic
sudo ufw allow 443/tcp

# Deny direct access to management port if separate
sudo ufw deny 8443/tcp

Complete Security Example

config.yaml

# Production-grade security configuration
host: ""
port: 443

# TLS encryption
tls:
  enable: true
  cert: "/etc/letsencrypt/live/api.company.com/fullchain.pem"
  key: "/etc/letsencrypt/live/api.company.com/privkey.pem"

# Client authentication
api-keys:
  - "sk-prod-a1b2c3d4e5f6..."  # Production key 1
  - "sk-prod-g7h8i9j0k1l2..."  # Production key 2

# Management access (localhost only)
remote-management:
  allow-remote: false
  secret-key: "$2a$10$...<bcrypt-hash>..."
  disable-control-panel: false

# WebSocket security
ws-auth: true

# Secure token storage
auth-dir: "/var/lib/switchailocal/auth"

# Logging for audit
logging-to-file: true
debug: false

Troubleshooting

Authentication failures

Problem: Requests return 401 UnauthorizedSolutions:

Verify Authorization: Bearer <key> header is included
Check key is in api-keys list
Ensure config.yaml has been reloaded
Check for typos in API key

Management API returns 404

Problem: Management endpoints return 404Solutions:

Ensure remote-management.secret-key is not empty
Check if disable-control-panel: true is set
Verify you’re accessing the correct endpoint

Remote management access denied

Problem: Management requests from network IPs return 403Solutions:

Set remote-management.allow-remote: true
Verify firewall allows traffic on the port
Ensure correct management secret key is used

Next Steps

Server Configuration

Configure host, port, logging, and core settings

Provider Setup

Add API keys for cloud and local AI providers

Get Started

Core Concepts

Configuration

Intelligent Systems

Advanced Features

Guides

API Key Authentication

Configuring API Keys

Key Rotation

Management Access Control

Management Secret Key

Remote Access Control

Management Control Panel

Disabling Management API

WebSocket Authentication

TLS/HTTPS Configuration

Production TLS Example

Authentication Directory

Security Best Practices

1. Use Strong API Keys

2. Enable TLS in Production

3. Restrict Management Access

4. Secure Authentication Directory

5. Rotate Keys Regularly

6. Use Environment-Specific Configs

Firewall Configuration

Complete Security Example

Troubleshooting

Next Steps

Server Configuration

Provider Setup

​API Key Authentication

​Configuring API Keys

​Key Rotation

​Management Access Control

​Management Secret Key

​Remote Access Control

​Management Control Panel

​Disabling Management API

​WebSocket Authentication

​TLS/HTTPS Configuration

​Production TLS Example

​Authentication Directory

​Security Best Practices

​1. Use Strong API Keys

​2. Enable TLS in Production

​3. Restrict Management Access

​4. Secure Authentication Directory

​5. Rotate Keys Regularly

​6. Use Environment-Specific Configs

​Firewall Configuration

​Complete Security Example

​Troubleshooting

​Next Steps

Server Configuration

Provider Setup

API Key Authentication

Configuring API Keys

Key Rotation

Management Access Control

Management Secret Key

Remote Access Control

Management Control Panel

Disabling Management API

WebSocket Authentication

TLS/HTTPS Configuration

Production TLS Example

Authentication Directory

Security Best Practices

1. Use Strong API Keys

2. Enable TLS in Production

3. Restrict Management Access

4. Secure Authentication Directory

5. Rotate Keys Regularly

6. Use Environment-Specific Configs

Firewall Configuration

Complete Security Example

Troubleshooting

Next Steps