FreeLLMAPI Unified API Key Format: Structure, Generation, and Usage

FreeLLMAPI authenticates all requests through a single unified API key that follows the format freellmapi-<48-hex-characters>, totaling 59 characters with an 11-character prefix and a 48-character hexadecimal suffix.

FreeLLMAPI simplifies authentication by using one unified API key for every request to the /v1 proxy endpoint. This key is automatically generated on first-run and stored encrypted in the project's SQLite database. Understanding the exact format and generation logic helps developers integrate the API correctly and troubleshoot authentication issues.

Unified API Key Structure

Format Specification

The unified API key in FreeLLMAPI follows a strict, predictable structure:

freellmapi-<48-hex-characters>

• Prefix: The literal string freellmapi- (11 characters) identifies the token as a FreeLLMAPI unified key.
• Suffix: A 24-byte cryptographically secure random value encoded as lowercase hexadecimal (48 characters).
• Total Length: Exactly 59 characters.

This format appears in the codebase as freellmapi-${crypto.randomBytes(24).toString('hex')} within the server implementation.

Validation Pattern

Any valid unified API key must match the regular expression:

^freellmapi-[a-f0-9]{48}$

Keys that deviate from this pattern—whether through incorrect length, missing prefix, or uppercase hexadecimal digits—will fail authentication against the proxy endpoints.

How FreeLLMAPI Generates the Unified Key

Runtime Generation in db/index.ts

The primary generation logic resides in server/src/db/index.ts. When the system initializes without an existing key, it executes:

`freellmapi-${crypto.randomBytes(24).toString('hex')}`

This call generates 24 random bytes and converts them to a 48-character hexadecimal string, ensuring sufficient entropy for production security.

First-Run Initialization in migrations.ts

The same pattern appears in server/src/db/migrations.ts (line 2237), where the key is first printed to the console during initial setup. This ensures administrators can copy the key immediately after installation before it is encrypted and stored in the SQLite database.

The README documentation also references this format using the placeholder freellmapi-your-unified-key, indicating exactly where users should substitute their generated key.

Using the Unified API Key

All requests to the FreeLLMAPI proxy must include the unified key in the Authorization header using the Bearer scheme.

cURL Authentication

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-0123456789abcdef0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "auto",
        "messages": [{"role": "user", "content": "Hello world"}]
      }'

Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-0123456789abcdef0123456789abcdef0123456789abcdef"
)

resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize the plot of Romeo and Juliet"}]
)

print(resp.choices[0].message.content)

Node.js Implementation

// Retrieve from UI or environment
const unifiedKey = process.env.FREELLMAPI_KEY || 
  document.querySelector('header .unified-key').textContent.trim();

await fetch('http://localhost:3001/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${unifiedKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ 
    model: 'auto', 
    messages: [{ role: 'user', content: 'Hi' }] 
  })
});

Security and Logging

FreeLLMAPI implements security measures to protect the unified key in production environments. The server/src/lib/error-redaction.ts module specifically scans logs and error messages for any tokens matching the freellmapi- prefix, automatically redacting them to prevent accidental credential exposure.

Additionally, the test suite in server/src/__tests__/routes/proxy-auth-cors.test.ts validates that the unified key is strictly required for all proxy calls, ensuring authentication middleware functions correctly across endpoints.

Summary

• FreeLLMAPI unified API keys follow the format freellmapi-<48-hex-characters> with a total length of 59 characters.
• Keys are generated using crypto.randomBytes(24) in server/src/db/index.ts and stored encrypted in SQLite.
• Authentication requires the Authorization: Bearer freellmapi-... header for all /v1 proxy requests.
• The regex pattern ^freellmapi-[a-f0-9]{48}$ validates key format.
• Keys are automatically redacted from logs by the error-redaction middleware.

Frequently Asked Questions

What is the exact length of a FreeLLMAPI unified key?

A valid FreeLLMAPI unified API key is exactly 59 characters long. This comprises an 11-character prefix (freellmapi-) plus a 48-character hexadecimal suffix representing 24 bytes of random data.

How is the unified API key generated?

The server generates the key using Node.js crypto.randomBytes(24).toString('hex') within server/src/db/index.ts. This produces 24 cryptographically secure random bytes encoded as 48 lowercase hexadecimal characters, prefixed with freellmapi-.

Where is the unified key stored?

After generation, the unified key is encrypted and stored in the project's SQLite database. It is printed to the console once during first-run initialization via server/src/db/migrations.ts (line 2237) so administrators can record it before it enters encrypted storage.

How do I validate a FreeLLMAPI key format?

Validate keys against the regex pattern ^freellmapi-[a-f0-9]{48}$. Any valid key must start with the literal prefix freellmapi-, followed by exactly 48 lowercase hexadecimal characters (0-9, a-f). Keys not matching this pattern will be rejected by the proxy authentication middleware tested in server/src/__tests__/routes/proxy-auth-cors.test.ts.

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