Authentication

Name: AletheionGuard
Rating: 4.8 (127 reviews)
Author: AletheionGuard

Learn how to authenticate your requests to the AletheionGuard API using API keys.

Quick Start

AletheionGuard API uses simple API key authentication via the X-API-Key header. All API requests (except health checks) require a valid API key.

API Key Authentication

Simple and secure authentication for all types of applications. API keys are configured via environment variables.

# Request header

X-API-Key: your_api_key_here

How Authentication Works

Configure API Key

The API is configured with an AG_API_KEY_SECRET environment variable. This is the master API key that clients must provide.

Include in Requests

Clients include the API key in the X-API-Key header with every request.

Constant-Time Verification

The API uses secrets.compare_digest() for constant-time comparison to prevent timing attacks (SEC-002).

Note: If AG_API_KEY_SECRET is not configured, the API runs in open mode (no authentication required). This is useful for development but should never be used in production.

Using API Keys

cURL

curl -X POST https://aletheionguard.onrender.com/v1/audit \

-H "X-API-Key: your_api_key" \

-H "Content-Type: application/json" \

-d '{

"text": "Paris is the capital of France",

"context": "What is the capital of France?"

Python (requests)

import requests

import os

api_key = os.getenv("ALETHEION_API_KEY")

headers = {

"X-API-Key": api_key,

"Content-Type": "application/json"

}

response = requests.post(

"https://aletheionguard.onrender.com/v1/audit",

headers=headers,

json={

"text": "Paris is the capital of France",

"context": "What is the capital of France?"

}

)

print(response.json())

JavaScript/Node.js

const apiKey = process.env.ALETHEION_API_KEY

const response = await fetch(

"https://aletheionguard.onrender.com/v1/audit",

{

method: "POST",

headers: {

"X-API-Key": apiKey,

"Content-Type": "application/json"

body: JSON.stringify({

text: "Paris is the capital of France",

context: "What is the capital of France?"

})

}

)

const data = await response.json()

Python (SDK)

from aletheion_guard import EpistemicAuditor

# SDK handles authentication internally

# No need to manually set API keys

auditor = EpistemicAuditor()

audit = auditor.evaluate(

text="Paris is the capital of France",

context="What is the capital of France?"

)

print(f"Verdict: {audit.verdict}")

Public Endpoints (No Auth Required)

The following endpoints do not require authentication:

Endpoint	Description
GET /	Root endpoint - API information
GET /health	Health check - service status
GET /docs	OpenAPI/Swagger documentation
GET /openapi.json	OpenAPI schema
GET /metrics	Prometheus metrics

Security Best Practices

✓ DO

Store API keys in environment variables, never in source code
Use different keys for development and production
Configure AG_API_KEY_SECRET in production
Use HTTPS for all API requests
Add .env to .gitignore
Rotate API keys periodically
Monitor API usage for suspicious activity

✗ DON'T

Hard-code API keys in your source code
Commit API keys to version control (use .env and .gitignore)
Share API keys via email or messaging apps
Expose API keys in client-side JavaScript
Run production without authentication enabled
Use the same key across multiple independent deployments

Authentication Errors

Common authentication errors and how to resolve them:

401

Unauthorized - Missing API Key

The X-API-Key header was not provided.

{

"error": "unauthorized",

"message": "Missing X-API-Key header"

}

Solution: Include the X-API-Key header in your request with a valid API key.

403

Forbidden - Invalid API Key

The provided API key does not match the configured secret.

{

"error": "forbidden",

"message": "Invalid API key"

}

Solution: Verify that your API key matches the AG_API_KEY_SECRET configured on the server. Check for typos or extra whitespace.

Environment Variables

Example configuration for different environments:

Client Configuration (.env)

# Your API key for authenticating with AletheionGuard

ALETHEION_API_KEY=your_secret_api_key_here

# API endpoint (production)

ALETHEION_API_URL=https://aletheionguard.onrender.com

Server Configuration (.env)

# Secret key that clients must provide

AG_API_KEY_SECRET=your_very_secret_key_here

# Optional: CORS origins (comma-separated)

CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

Important: Add .env to your .gitignore file to prevent accidentally committing secrets to version control.

Technical Implementation

Security Features

•Constant-time comparison: Uses secrets.compare_digest() to prevent timing attacks (SEC-002)
•Middleware-based: Authentication is enforced at the middleware level before reaching endpoints
•Public endpoints: Health checks and docs are exempt from authentication
•Optional mode: Can run without authentication for development (not recommended for production)
•CORS protection: Configurable CORS origins via CORS_ORIGINS environment variable (SEC-008)

Implementation: See src/aletheion_guard/security.py for the verify_api_key() function and src/aletheion_guard/api.py for the authentication middleware (lines 138-172).