FreeLLMAPI Authentication Flow: Dashboard vs API Access Explained

FreeLLMAPI separates human and machine access via two distinct authentication mechanisms: email/password sessions for the admin dashboard and encrypted unified API keys for programmatic LLM proxy requests.

The tashfeenahmed/freellmapi repository implements a dual-layer authentication system that protects administrative interfaces differently from programmatic endpoints. Understanding the FreeLLMAPI authentication flow is essential for securely managing both dashboard users and API consumers. Each authentication domain uses separate storage tables, encryption methods, and middleware validation logic.

Dashboard Authentication Flow (Email/Password)

Login Endpoint and Credential Verification

The dashboard authentication begins at POST /api/auth/login defined in server/src/routes/auth.ts. The endpoint receives a JSON payload containing { "email": "...", "password": "..." } and invokes verifyCredentials from server/src/services/auth.ts. This function normalizes the email address, retrieves the password_hash from the users table, and validates it against verifyPassword.

Session Creation and Storage

Upon successful credential verification, createSession(userId) generates a cryptographically random 32-byte token. The system stores sha256(token) in the sessions table alongside the user ID and expiration timestamp. The plaintext token is returned to the client, typically as JSON { token } or via a Set-Cookie header. Sessions automatically expire after 30 days (SESSION_TTL_MS) and are purged from the database when invalid.

Protected Route Middleware

Dashboard routes utilize the requireAuth middleware located in server/src/middleware/requireAuth.ts. This middleware extracts the token from the Authorization: Bearer <token> header or cookie, then calls validateSession(token). The validation retrieves the session row, verifies the SHA-256 hash, checks expiration, and returns the associated SessionUser object. Invalid or expired tokens trigger a 401 authentication_error response.

API Authentication Flow (Unified API Keys)

API Key Creation and Encryption

Administrators generate unified API keys through the dashboard's Keys page or CLI tools. The raw key undergoes AES-GCM encryption via helpers in server/src/lib/crypto.ts (encrypt and decrypt functions) before storage. Encrypted keys reside in the api_keys table (defined in shared/types.ts) with associated metadata including platform, enabled status, and health status. The system also maintains a default key reference in the settings table under unified_api_key.

Request Verification Process

API requests hit the proxy handler in server/src/routes/proxy.ts. The handler extracts the key from headers, queries the api_keys table for rows matching platform = 'unified' with enabled = 1 and status in ('healthy','unknown'). The stored encrypted_key, iv, and auth_tag are decrypted using server/src/lib/crypto.ts utilities. The request proceeds only if the decrypted key matches the supplied credential.

Header Formats and Validation

The proxy accepts API keys via two header formats:

• Authorization: Bearer <api-key>
• x-api-key: <api-key>

Failed validation returns a 401 authentication_error. Unlike dashboard sessions, API keys do not expire automatically and remain valid until manually disabled via the UI.

Architecture Comparison

Aspect	Dashboard Access	API Access
Credential Type	Email + password	Unified API key (opaque string)
Storage	users and sessions tables	api_keys table with AES-GCM encryption
Verification	verifyPassword and validateSession	Decryption via server/src/lib/crypto.ts
Expiration	30 days (SESSION_TTL_MS)	No automatic expiration
Protected Routes	/api/* admin endpoints	/v1/* LLM proxy endpoints

Practical Implementation Examples

Authenticate via the dashboard and access admin endpoints:

# Obtain session token via email/password

TOKEN=$(curl -s -X POST https://free-llmapi.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"supersecret"}' \
  | jq -r '.token')

# Use token to list API keys

curl https://free-llmapi.example.com/api/keys \
  -H "Authorization: Bearer $TOKEN"

Access LLM endpoints using the unified API key:

curl https://free-llmapi.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-abcdef1234567890" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'

Summary

• FreeLLMAPI maintains separate authentication domains for human administrators and automated API clients.
• Dashboard sessions rely on bcrypt-hashed passwords and SHA-256 hashed session tokens with 30-day expiration.
• API keys use AES-GCM encryption at rest and support both Authorization: Bearer and x-api-key header formats.
• The requireAuth middleware protects admin routes while the proxy handler in server/src/routes/proxy.ts validates API keys against encrypted database entries.
• Session tokens are ephemeral and rotated automatically, whereas API keys persist until manually revoked.

Frequently Asked Questions

How long do dashboard sessions remain valid in FreeLLMAPI?

Dashboard sessions expire after 30 days as defined by SESSION_TTL_MS in the configuration. The validateSession function in server/src/services/auth.ts automatically checks expiration timestamps and rejects expired tokens with a 401 error.

What encryption method protects API keys in the database?

FreeLLMAPI uses AES-GCM encryption implemented in server/src/lib/crypto.ts. The encrypt function generates initialization vectors and authentication tags stored alongside the ciphertext in the api_keys table.

Can API keys expire automatically like dashboard sessions?

No. According to the source code in server/src/routes/proxy.ts, API keys do not implement automatic expiration. Keys remain active until an administrator changes the status to disabled or deletes the row via the dashboard.

Which middleware file enforces authentication for admin dashboard routes?

The requireAuth middleware located at server/src/middleware/requireAuth.ts validates session tokens for all protected dashboard endpoints. It extracts tokens from the Authorization header or cookies and verifies them against the sessions table.

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