Skip to content

Latest commit

 

History

History
118 lines (90 loc) · 4.06 KB

API_AUTHENTICATION.md

File metadata and controls

118 lines (90 loc) · 4.06 KB

API Authentication Guide

SAM's API server now requires authentication for all external requests to protect against unauthorized access.

Security Model

Internal Requests (SAM UI)

  • No Authentication Required
  • SAM's user interface communicates with the API through direct Swift function calls
  • No HTTP requests are made to localhost
  • This provides the highest level of security as communication never leaves the process

External Requests (API Clients)

  • Bearer Token Authentication Required
  • All HTTP requests to the API must include a valid Bearer token
  • Tokens are stored in UserDefaults for convenient access
  • Only the /health endpoint remains public

Getting Your API Token

  1. Open SAM Preferences → API Server
  2. Your token is displayed in the "API Authentication" section
  3. Click the copy button (📋) to copy it to your clipboard
  4. Keep this token secure - it provides full access to your SAM API

Using the Token

Include your token in the Authorization header of all API requests:

curl -X POST http://localhost:8080/api/chat/completions \
  -H "Authorization: Bearer YOUR-TOKEN-HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Token Management

Copying Your Token

Click the copy button in Preferences → API Server to copy your token to the clipboard.

Regenerating Your Token

  1. Click the regenerate button (🔄) in Preferences → API Server
  2. Confirm the regeneration
  3. Update all external clients with the new token
  4. Old token is immediately invalidated

Security Best Practices

  • Never share your API token in public repositories or communications
  • Regenerate your token if you suspect it has been compromised
  • Use environment variables to store tokens in scripts
  • Disable "Allow Remote Access" unless you specifically need network access

Error Responses

401 Unauthorized - Missing Token

{
  "error": "Missing Authorization header. API access requires a Bearer token."
}

401 Unauthorized - Invalid Token

{
  "error": "Invalid API token. Please use the correct token from SAM Preferences → API Server."
}

Remote Access Warning

When "Allow Remote Access" is enabled in Preferences:

  • ⚠️ WARNING: Your API becomes accessible to anyone on your local network who has your token
  • The server binds to 0.0.0.0 instead of 127.0.0.1
  • Only enable this when you need to access SAM from other devices on your network
  • Consider using a firewall to restrict access to specific IP addresses

Implementation Details

Architecture

  • UserDefaults Storage: API tokens are stored in UserDefaults for quick access without keychain prompts
  • APITokenMiddleware: Vapor middleware for token validation with caching
  • Token Format: Two concatenated UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000-7c9e6679-7425-40de-944b-e07fc1f90ae7)

Security Features

  • Token generation uses secure random number generation (UUID)
  • Tokens are validated on every request
  • Token cached in memory to minimize UserDefaults access
  • Internal SAM UI communication bypasses authentication entirely (more secure)
  • UserDefaults provides sufficient security for localhost-only API access

Why Direct Function Calls Are Better

SAM's internal architecture uses direct Swift function calls instead of HTTP:

SAM UI → SharedConversationService → EndpointManager → Provider

This design:

  • Eliminates HTTP overhead for internal operations
  • Prevents token interception or tampering
  • Provides the smallest possible attack surface
  • Ensures fastest possible response times

External API access via HTTP is only needed for tools like:

  • curl scripts
  • Python integrations
  • VS Code extensions
  • Aider and other developer tools

Migration Notes

For users upgrading from versions without authentication:

  • A token is automatically generated on first launch of the new version
  • Existing API integrations will need to be updated with the new token
  • The token can be found in Preferences → API Server → API Authentication