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

> Learn how the unified bearer token in FreeLLMAPI simplifies authentication for OpenAI-compatible endpoints, granting access to multiple LLM providers with one secret.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash
freellmapi keys get

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

```

Make authenticated requests using the standard Authorization header:

```bash
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:

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/auth.ts).
- This architecture simplifies client-side configuration while the router service ([`server/src/services/router.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.