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

> Learn the unified API key format for FreeLLMAPI. Discover how to structure, generate, and use your freellmapi-<48-hex-characters> key for seamless authentication.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: api-reference
- Published: 2026-06-26

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/db/index.ts)**. When the system initializes without an existing key, it executes:

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

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

```python
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

```javascript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/__tests__/routes/proxy-auth-cors.test.ts).