API Gateway

The API Gateway is the single entry point for all client traffic in AEGIS. It is a Go reverse proxy that handles authentication, rate limiting, CORS, and request routing to the appropriate backend microservice.

Overview

Every request from the frontend (or any external client) passes through the API Gateway on port 8000 before reaching a backend service. The gateway validates the JWT (from the Authorization header or the aegis_token cookie), enforces rate limits, attaches CORS headers, and rewrites URL paths before proxying requests to the correct upstream service.

The gateway strips CORS headers from backend responses to ensure it is the single source of truth for cross-origin policy.

Port & Language

Middleware Stack

Requests pass through the middleware chain in this order (reordered in R42b — auth now runs before the rate limiter so the limiter keys per-user; behind Caddy every remote address is 127.0.0.1, so IP keying would collapse all users onto one bucket):

Client Request → CORS → Auth → Rate Limiter → Route Handler → Backend Service

1. CORS Middleware

Adds permissive CORS headers to every response and short-circuits OPTIONS preflight requests with a 200 OK.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Backend CORS headers are stripped by the reverse proxy’s ModifyResponse hook to prevent conflicts.

2. Auth Middleware

Authenticates the request and authorizes it fresh-at-perimeter (R42b). Authentication is JWT only — the gateway no longer accepts the X-API-Key header.

Where the JWT is read from (in order):

1. Authorization: Bearer <token> header — the standard case for API clients.
2. aegis_token cookie — the browser case (httpOnly since R42b; also covers SSE/EventSource clients that cannot set headers).

The token is first validated locally using HMAC-SHA256 with the JWT_SECRET environment variable (fast reject). Then the gateway consults its resolve client (internal/resolver): an in-memory cache keyed sha256(token) fronting auth-service’s POST /auth/resolve.

• Cached results ≤5s old are served without a network call.
• Older entries are re-fetched with a 500ms timeout.
• If auth-service errors, a stale entry keeps being served up to 60s old (stale-while-revalidate — an auth-service restart does not take the platform down).
• Beyond 60s stale, the request fails closed with 401.

The middleware stamps X-User-Id, X-User-Email (R42d), X-Roles, X-Tenant-Id, and X-Permissions onto the proxied request from the resolve result (not raw JWT claims) — inbound copies of these headers are stripped on every path first, so clients cannot spoof them — and role changes and deactivation bind on live traffic within ~5 seconds. The gateway has no Postgres client — auth-service stays the sole identity SQL surface. Cache hit rates and stale-served counts are logged once a minute (resolve cache: …).

Since R42d the stamped headers are not merely informational: every Python service verifies them via aegis_shared.auth dependencies (mode-gated by AEGIS_AUTH_MODE), so the gateway is the first of two authorization layers. See Auth Flow — Service-Side Enforcement.

Unauthenticated routes (auth skipped):

• /health
• /api/v1/auth/token
• /api/v1/auth/logout (so a client with an expired token can still clear its cookie)
• /api/v1/auth/invites/* (public invite validation/redemption)
• /api/v1/entity-types*
• /api/v1/relationship-rules*
• /api/v1/relationship-types*

/api/v1/auth/resolve is deliberately NotFound’d — internal-only, same pattern as rules/evaluate.

3. Rate Limiter

Per-user token bucket rate limiter using golang.org/x/time/rate:

• Rate: 600 requests per minute (10 req/sec)
• Burst: 100 requests (dashboard pages burst-fetch on mount)
• Key: authenticated user_id from context (set by the auth middleware); remote address only for public paths

When the limit is exceeded, the gateway returns 429 Too Many Requests.

Routing Rules

The gateway maps public API paths (prefixed with /api/v1/) to internal service paths. Each upstream service is configured via environment variables with sensible localhost defaults.

Route Table

Role-Based Access Control

Some routes enforce role checks before proxying:

• /api/v1/admin/* — Requires the admin role. Returns 403 Forbidden otherwise.
• /api/v1/detection-rules* — Requires power_user or admin role.

Roles come from the DB-fresh resolve result and are placed into the request context by the auth middleware. These route-level checks are coarse; fine-grained permission checks (hitl.approve, filings.submit, …) happen in the services themselves since R42d.

Architecture

cmd/gateway/main.go              # Entry point, middleware chain assembly
internal/
├── auth/
│   └── jwt.go                   # JWT parsing, validation, generation (HS256)
├── middleware/
│   ├── auth.go                  # Auth middleware (JWT only — header or cookie)
│   ├── cors.go                  # CORS header injection
│   └── ratelimit.go             # Per-client token bucket rate limiter
└── proxy/
    └── routes.go                # Route registration, reverse proxy setup

JWT Claims Structure

type Claims struct {
    UserID string   `json:"user_id"`
    Roles  []string `json:"roles"`
    jwt.RegisteredClaims
}

Tokens are signed with HS256 and expire after 24 hours. The issuer is set to aegis-gateway.

Dependencies

The gateway has no database dependencies. It proxies all persistence to backend services.

Service Dependencies

The gateway calls the auth-service (port 8009) for token generation. JWT validation is done locally using the shared JWT_SECRET. All other backend services are called only as reverse proxy targets.

Configuration

Running Locally

cd services/api-gateway
go run ./cmd/gateway/

The gateway will start on port 8000 and log the upstream service URLs it is configured to proxy to. Make sure the backend services you need are running before sending requests through the gateway.