Authentication

MXHook uses API key authentication to protect the REST API.

API Key

Set the API key via environment variable or CLI flag:

# Environment variable
MXHOOK_API_KEY=your-secret-key

# CLI flag
./mxhook start --api-key your-secret-key

Usage

Include the key in the X-API-Key header on every request:

curl http://localhost:8080/domains \
  -H "X-API-Key: your-secret-key"

Behavior

Configuration	Behavior
API key is set	All endpoints (except /health and /openapi.yaml) require the header
API key is empty	No authentication is required on any endpoint

Error Response

Missing or invalid API key returns 401 Unauthorized:

{
  "error": "unauthorized"
}

Public Endpoints

These endpoints never require authentication:

Endpoint	Description
GET /health	Health check
GET /openapi.yaml	OpenAPI specification

Recommendations

• Always set an API key in production. Without one, anyone with network access to the API can manage your domains, routes, and messages.
• Use a strong, random key. Generate one with: openssl rand -hex 32
• Rotate keys by restarting MXHook with a new MXHOOK_API_KEY value.
• Use HTTPS. Place the API behind a TLS-terminating reverse proxy to prevent the key from being intercepted in transit.