# FreeLLMAPI Authentication Flow: Dashboard vs API Access Explained

> Understand the FreeLLMAPI authentication flow for dashboard and API access. Learn how to secure your LLM proxy requests with email/password or unified API keys.

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

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts). The endpoint receives a JSON payload containing `{ "email": "...", "password": "..." }` and invokes `verifyCredentials` from [`server/src/services/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts) (`encrypt` and `decrypt` functions) before storage. Encrypted keys reside in the `api_keys` table (defined in [`shared/types.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash

# 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":"admin@example.com","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:

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