API Authentication¶

FenLiu protects its REST API endpoints with API key authentication. This guide explains how to create and use API keys.

Overview¶

All requests to protected API endpoints must include a valid API key in the X-API-Key header. API keys are stored securely and cannot be retrieved after initial generation.

Generating an API Key¶

Via the Settings Page (Recommended)¶

Log in to FenLiu and navigate to Settings
Scroll to the API Key Management section
Click the Generate New API Key button
A confirmation dialog will appear asking if you want to proceed
Your new API key will be displayed in an amber box
Important: Copy and save your API key immediately — it will never be shown again
Store it securely in your application, password manager, or environment variables

Important Notes¶

Each new key overwrites the previous one — only one API key can be active at a time
The API key is only displayed immediately after generation
API keys cannot be retrieved later, even by administrators
If you lose your API key, you must generate a new one

Using Your API Key¶

Include your API key in the X-API-Key header for all requests to protected endpoints:

curl -H "X-API-Key: your-api-key-here" \  # pragma: allowlist secret
  http://localhost:8000/api/v1/posts

Python Example¶

import httpx

api_key = "your-api-key-here"  # pragma: allowlist secret
headers = {"X-API-Key": api_key}

async with httpx.AsyncClient() as client:
    response = await client.get(
        "http://localhost:8000/api/v1/posts",
        headers=headers
    )
    posts = response.json()

JavaScript/Node.js Example¶

const apiKey = "your-api-key-here";  // pragma: allowlist secret

fetch("http://localhost:8000/api/v1/posts", {
  headers: {
    "X-API-Key": apiKey
  }
})
  .then(res => res.json())
  .then(posts => console.log(posts))
  .catch(err => console.error(err));

Protected Endpoints¶

All /api/v1/* endpoints require API key authentication, except:

GET /api/v1/api-keys/status — Check if an API key is configured
POST /api/v1/api-keys/generate — Generate a new API key
POST /api/v1/api-keys/revoke — Revoke the current API key

These endpoints are accessible without authentication for settings page functionality.

API Key Management Endpoints¶

Check API Key Status¶

Endpoint: GET /api/v1/api-keys/status

Authentication: Not required

Response:

{
  "api_key_set": true,
  "message": "API key is set"
}

Generate New API Key¶

Endpoint: POST /api/v1/api-keys/generate

Authentication: Not required

Response (Status: 201 Created):

{
  "success": true,
  "api_key": "abc123def456...",  # pragma: allowlist secret
  "message": "API key generated successfully. Store it safely - you won't see it again!"
}

Revoke API Key¶

Endpoint: POST /api/v1/api-keys/revoke

Authentication: Not required

Response:

{
  "success": true,
  "message": "API key revoked successfully"
}

Security Best Practices¶

Never commit API keys to version control. Use environment variables instead:
```
export FENLIU_API_KEY="your-api-key-here"  # pragma: allowlist secret
```
Use HTTPS in production to protect keys in transit
Rotate keys periodically by generating a new key and updating your applications
Treat your API key like a password — don't share it or expose it in client-side code
Use separate keys for different applications if possible (currently only one key is supported, but consider this for future deployments)
Monitor API usage through logs if available

Error Handling¶

Missing API Key¶

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": "Unauthorized: Invalid or missing API key"
}

Invalid API Key¶

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": "Unauthorized: Invalid or missing API key"
}

Troubleshooting¶

"Unauthorized: Invalid or missing API key"¶

Verify the API key is included in the X-API-Key header
Ensure you copied the entire key without extra spaces or characters
Check that an API key is actually configured (use the status endpoint)
Generate a new key if the old one was lost

API Key Not Saving¶

Ensure cookies are enabled in your browser (required for settings page)
Try generating the key again
Check browser console for errors

Lost API Key¶

Generate a new one via the settings page
The old key is automatically invalidated
Update all applications using the old key