Authentication

The Apollon API uses API key authentication via the X-API-Key HTTP header.

How It Works

Every request (except exempt paths) must include a valid API key:

curl -H "X-API-Key: your-api-key-here" http://localhost:3000/v1/trips

The middleware checks the X-API-Key header value against the configured list of valid API keys. If the key matches any entry in the list, the request is authorized.

Configuration

API keys are configured via the auth.api_keys array in the config file or the APOLLON__AUTH__API_KEYS environment variable.

Config File (TOML)

[auth]
api_keys = ["key-1-abc123", "key-2-def456"]

Environment Variable

APOLLON__AUTH__API_KEYS="key-1-abc123,key-2-def456"

Disabling Authentication

When the api_keys list is empty (or not set), authentication is completely disabled and all requests pass through unconditionally. This is the default for local development.

[auth]
api_keys = []

Exempt Paths

The following paths bypass API key authentication regardless of configuration:

Path	Description
/health	System health check
/v1/swagger-ui	Swagger UI (all sub-paths)
/v1/graphiql	GraphiQL IDE
/v1/openapi.json	OpenAPI specification
/v1/schema	GraphQL SDL schema

Path matching uses prefix comparison, so /v1/swagger-ui/index.html is also exempt.

Error Response

When authentication fails, the API returns 401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "A valid X-API-Key header is required"
}

This response is returned when:

• The X-API-Key header is missing
• The X-API-Key header value does not match any configured key

Security Notes

• API keys are compared as plain strings -- use long, random values
• Keys are stored in memory as Vec<String> -- avoid excessive numbers
• The middleware runs after CORS and before rate limiting in the stack
• WebSocket connections at /ws are subject to API key auth (not in the exempt list)
• Use HTTPS in production to prevent key interception