Authentication¶

Every API request must be authenticated. Two methods are supported: API keys (recommended for integrations) and JWT tokens (for user sessions).

API Keys¶

API keys are the simplest way to authenticate. Include the key in the X-API-Key header.

curl -H "X-API-Key: hai_your_key_here" \
  http://localhost:8100/api/v1/documents/stats

Generating API keys¶

from haagsman_core.auth import generate_api_key
key = generate_api_key()
print(key)  # hai_Ab3x9Kf2...

Key format¶

All API keys start with hai_ (haagsman.ai) followed by 43 characters of URL-safe random data.

JWT Tokens¶

For user-facing applications, use JWT tokens with short-lived access tokens and longer-lived refresh tokens.

Get tokens¶

# Login (returns access + refresh tokens)
curl -X POST http://localhost:8100/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@company.com", "password": "..."}'

Use the access token¶

curl -H "Authorization: Bearer eyJhbG..." \
  http://localhost:8100/api/v1/search/query \
  -d '{"query": "What is our refund policy?"}'

Token lifetimes¶

Token	Default Lifetime	Configurable
Access token	15 minutes	`HAAGSMAN_JWT_ACCESS_TOKEN_TTL_MINUTES`
Refresh token	7 days	`HAAGSMAN_JWT_REFRESH_TOKEN_TTL_DAYS`

Role-Based Access Control (RBAC)¶

Three roles with escalating permissions:

Role	Read	Write	Delete	Manage Users	View Audit	Configure
Viewer	:material-check:
Operator	:material-check:	:material-check:	:material-check:		:material-check:
Admin	:material-check:	:material-check:	:material-check:	:material-check:	:material-check:	:material-check:

What each role can do¶

Viewer: Search documents, chat with FAQ bot, view triage results. Cannot upload or modify.
Operator: Everything viewers can do, plus upload documents, delete entries, view audit logs.
Admin: Full access including user management, GDPR operations, and system configuration.

Security best practices¶

Recommendations

Use API keys for server-to-server integrations
Use JWT tokens for user-facing applications
Rotate API keys every 90 days
Use the Viewer role for read-only integrations
Never expose API keys in client-side JavaScript — use a backend proxy
Monitor the audit log for unusual access patterns

Rate limiting¶

All endpoints are rate-limited per API key / user. Default: 60 requests per minute.

When rate-limited, you'll receive:

{"detail": "Rate limit exceeded. Try again later."}

HTTP status: 429 Too Many Requests