What Is the Unified Bearer Token in FreeLLMAPI? Authentication and Usage Guide

The unified bearer token is a single API secret that authorizes all client requests to FreeLLMAPI's OpenAI-compatible inference endpoints, aggregating access to dozens of LLM providers without requiring separate credentials for each upstream service.

FreeLLMAPI operates as an open-source gateway that combines free-tier quotas from multiple LLM providers into a single OpenAI-compatible API surface. The unified bearer token functions as the sole authentication credential for every inference request, simplifying client configuration while the gateway internally manages individual provider keys.

How the Unified Bearer Token Works

When the FreeLLMAPI server initializes, it generates or retrieves a cryptographic secret stored in the SQLite database under the settings key unified_api_key. This initialization is handled by the migration script located at server/src/db/migrations/20260101_000000_legacy_baseline.ts, which ensures the token exists before any client requests are accepted.

The token acts as a master key that grants access to the aggregated free quotas of all configured providers. Unlike traditional API gateways that require separate authentication for each backend service, FreeLLMAPI abstracts this complexity behind a single credential.

Retrieving Your Token

Users can access the unified bearer token through two primary interfaces:

• Dashboard: The "Keys" page displays the current token for copy-paste usage
• CLI Tool: Running freellmapi keys get outputs the token directly to the terminal, as implemented in cli/src/tools.ts

Authenticating Requests with the Bearer Token

All requests targeting the inference surface must include the unified bearer token in their headers. The proxy middleware defined in server/src/routes/proxy.ts (lines 71-75) extracts credentials from incoming requests and enforces authentication before routing to upstream providers.

Supported Header Formats

FreeLLMAPI accepts the token through two header patterns for backward compatibility:

1. Standard Bearer Token: Authorization: Bearer <token>
2. Legacy API Key: x-api-key: <token>

Both methods receive identical treatment during validation. The system performs a timing-safe comparison between the extracted credential and the stored unified_api_key value to prevent timing attacks.

Validation and Error Handling

If the provided token matches the stored secret, the request proceeds to the router service for provider selection. On mismatch, the server immediately returns 401 Unauthorized without processing the request body. This validation logic is comprehensively tested in server/src/__tests__/routes/proxy-auth-cors.test.ts (lines 36-56).

Scope and Limitations of the Unified Token

The unified bearer token operates under strict route scoping to maintain security boundaries.

Inference Endpoints Only: The token exclusively authorizes routes under /v1/*, /mcp, and Ollama-compatible endpoints. These paths handle chat completions, model listings, and streaming responses.

Separate Admin Authentication: Administrative routes under /api/* utilize a distinct session-based authentication system defined in server/src/services/auth.ts, requiring email and password credentials rather than the bearer token.

No Dashboard Privileges: Possessing the unified token does not grant access to the web dashboard, settings modification, or provider configuration. It solely permits consumption of the aggregated inference quota.

Why FreeLLMAPI Uses a Single Token Architecture

The unified bearer token design prioritizes operational simplicity and security isolation.

Simplified Client Configuration: Developers store only one secret in their applications regardless of how many upstream providers (OpenAI, Anthropic, Google, etc.) are available through the gateway. This eliminates configuration drift and reduces credential management overhead.

Internal Provider Abstraction: As implemented in server/src/services/router.ts (line 677), the gateway uses the validated unified token to look up encrypted provider-specific credentials stored in the database. The router then selects the healthiest available model based on quota status and request parameters, transparently handling the mapping between the single client token and multiple backend services.

Practical Code Examples

Retrieve your token using the CLI:

freellmapi keys get

# Output: Unified API key: freellmapi-0a1b2c3d4e5f6g7h8i9j...

Make authenticated requests using the standard Authorization header:

curl -X POST https://localhost:3001/v1/chat/completions \
     -H "Authorization: Bearer freellmapi-0a1b2c3d4e5f6g7h8i9j…" \
     -H "Content-Type: application/json" \
     -d '{
           "model": "gpt-3.5-turbo",
           "messages": [{"role":"user","content":"Hello"}]
         }'

For legacy clients or specific tool integrations, use the alternative header format:

curl -X POST https://localhost:3001/v1/chat/completions \
     -H "x-api-key: freellmapi-0a1b2c3d4e5f6g7h8i9j…" \
     -H "Content-Type: application/json" \
     -d '{"model": "claude-instant", "messages": [{"role":"user","content":"Hello"}]}'

Summary

• The unified bearer token is the single authentication credential required for all FreeLLMAPI inference requests, stored in SQLite under the key unified_api_key.
• Clients authenticate via either Authorization: Bearer <token> or the legacy x-api-key header, with validation occurring in server/src/routes/proxy.ts.
• The token exclusively grants access to inference endpoints (/v1/*, /mcp, Ollama); administrative functions require separate email/password authentication via server/src/services/auth.ts.
• This architecture simplifies client-side configuration while the router service (server/src/services/router.ts) securely maps the unified token to individual encrypted provider credentials.
• The token can be retrieved through the CLI command freellmapi keys get or the dashboard "Keys" page.

Frequently Asked Questions

How do I regenerate the unified bearer token if it is compromised?

FreeLLMAPI stores the token in the SQLite settings table under unified_api_key. To rotate the credential, you must update this database value directly or use any future CLI rotation commands added to cli/src/tools.ts. After regeneration, previous tokens become invalid immediately, requiring clients to update their Authorization headers.

What is the difference between the unified bearer token and individual provider API keys?

The unified bearer token is the single credential clients use to access the FreeLLMAPI gateway, while provider API keys are encrypted secrets stored server-side that the gateway uses to authenticate with upstream services like OpenAI or Anthropic. Clients never handle provider keys directly; the router service manages these internally based on the validated unified token.

Can I use the unified bearer token to access the admin dashboard or modify settings?

No. The unified bearer token explicitly authorizes only inference endpoints. Administrative routes under /api/* require session-based authentication using email and password credentials as defined in server/src/services/auth.ts. Attempting to use the bearer token on admin endpoints returns authentication errors.

Is the unified bearer token validation vulnerable to timing attacks?

No. The authentication logic in server/src/routes/proxy.ts performs timing-safe comparisons when validating the extracted token against the stored unified_api_key. This cryptographic best practice prevents attackers from inferring valid tokens through statistical timing analysis of the validation response times.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}