Authentication

AFA supports two authentication methods with automatic fallback.

Auth flow

1. Extract Authorization: Bearer <token> header
2. If Unkey is configured and the token is valid --> authenticate via Unkey (primary)
3. Otherwise, check X-AFA-Token header --> legacy HMAC authentication (fallback)
4. If no auth is configured --> open access (self-hosted / development)

Unkey API keys (primary)

API keys provisioned through the portal use Unkey for verification and rate limiting. Keys are prefixed with uk_afa_.

curl -H "Authorization: Bearer uk_afa_abc123..." \
  https://api.afa.undercurrentholdings.com/v1/analyze \
  -d '{"code": "def hello(): pass", "language": "python"}'

Each key is tied to a customer and tier. Unkey enforces:

• Rate limits per tier (requests per minute)
• Key metadata (customer ID, tier, product)
• Key revocation (immediate via portal or API)

Legacy token (fallback)

For self-hosted deployments or development, use the X-AFA-Token header:

curl -H "X-AFA-Token: your-secret-token" \
  http://localhost:8080/v1/analyze \
  -d '{"code": "def hello(): pass", "language": "python"}'

Set the expected token via environment variable:

export AFA_SERVER_API_TOKEN="your-secret-token"

Or in .afa.yaml:

server:
  api_token: "your-secret-token"

When no api_token is configured, the server runs in open access mode (no authentication required).

Rate limits by tier

When you exceed the rate limit, AFA returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{"error": "Rate limit exceeded"}

Feature gating

Some endpoints require specific tier features. The require_feature() dependency checks the caller's tier.

Current enforcement scope: Feature gating is enforced on REST API endpoints (rest_api on /v1/analyze and /v1/enhance). CLI and MCP server run locally without tier restrictions. Additional feature gates are being added incrementally.

If a feature is not available on your tier:

HTTP/1.1 403 Forbidden

{
  "error": "Feature 'rest_api' requires a higher tier. Current tier: Community. Upgrade at https://api.afa.undercurrentholdings.com/billing"
}

Legacy auth and open access modes allow all features (self-hosted deployments have no restrictions).