API Gateway

The API Gateway is the single point of entry for all external traffic into the MATIH platform. Built on Kong 3.5.0, it handles request routing, JWT authentication, tenant context injection, rate limiting, and security filtering. Every request from a browser, CLI tool, or external API client passes through this gateway before reaching any backend service.

Gateway Architecture

                        +---------------------------+
                        |        Internet           |
                        +------------+--------------+
                                     |
                        +------------v--------------+
                        |     Load Balancer (L4)    |
                        +------------+--------------+
                                     |
                        +------------v--------------+
                        |    Kong API Gateway       |
                        |    (Port 8080)            |
                        |                           |
                        |  +---------------------+  |
                        |  | Custom Lua Plugins  |  |
                        |  | - JWT Extraction    |  |
                        |  | - Tenant Rate Limit |  |
                        |  | - Request Validation|  |
                        |  +---------------------+  |
                        |                           |
                        +---+----+----+----+----+---+
                            |    |    |    |    |
                            v    v    v    v    v
                         Backend Services (REST APIs)

Kong 3.5.0 Configuration

The gateway is deployed via Helm chart with the following configuration:

Declarative Configuration

Kong runs in DB-less mode, meaning all routing and plugin configuration is declared in a YAML file rather than stored in a database. This approach provides:

• Immutability: Configuration is version-controlled alongside application code
• Reproducibility: Every environment gets the exact same gateway configuration
• Speed: No database dependency means faster startup and failover
• GitOps compatibility: Configuration changes go through the same PR review process as code

Custom Lua Plugins

The gateway uses three custom Lua plugins that extend Kong's built-in functionality:

1. JWT Claims Extraction Plugin

This plugin extracts tenant_id, user_id, and roles from the validated JWT token and injects them as HTTP headers for downstream services:

Behavior:

Incoming Request:
  Authorization: Bearer eyJhbGci...

After Plugin Execution:
  Authorization: Bearer eyJhbGci...  (preserved)
  X-Tenant-ID: acme-corp             (extracted from JWT)
  X-User-ID: user-123                (extracted from JWT)
  X-User-Roles: data_analyst,viewer  (extracted from JWT)
  X-Request-ID: req-abc-456          (generated if missing)
  X-Correlation-ID: cor-def-789      (generated if missing)

Why a custom plugin? Kong's built-in JWT plugin validates tokens but does not extract custom claims into headers. The MATIH platform needs tenant_id propagated as a header so that backend services can establish tenant context without re-parsing the JWT.

Processing Steps:

1. Validate the JWT signature against the signing key from IAM service
2. Check token expiration and issuer claims
3. Extract tenant_id from the tenant_id claim
4. Extract sub (user ID) from the standard subject claim
5. Extract roles from the roles claim
6. Set headers: X-Tenant-ID, X-User-ID, X-User-Roles
7. Generate X-Request-ID and X-Correlation-ID if not present in the request

2. Tenant Rate Limiting Plugin

This plugin enforces per-tenant rate limits that are configurable through the config-service:

Rate Limit Tiers:

Rate Limit Headers:

The plugin adds standard rate limit headers to every response:

X-RateLimit-Limit: 600           # Total allowed requests
X-RateLimit-Remaining: 542       # Remaining requests in window
X-RateLimit-Reset: 1707700800    # Window reset timestamp (epoch)

When a tenant exceeds their limit, the gateway returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 45

{
  "error": "Rate limit exceeded",
  "message": "Tenant 'acme-corp' has exceeded 600 requests/minute limit",
  "retryAfter": 45
}

Implementation Details:

• Rate counters are stored in Redis with sliding window algorithm
• Counters are keyed by ratelimit:{tenant_id}:{window}
• The plugin checks tenant tier by looking up the X-Tenant-ID header and querying the config-service cache

3. Request Validation Plugin

This plugin performs input validation at the gateway level before requests reach backend services:

Validations Performed:

Routing Configuration

The gateway routes requests to backend services based on URL path prefixes:

Control Plane Routes

Data Plane Routes

Public Routes (No Authentication)

A small set of routes are accessible without authentication:

Upstream Service Discovery

The gateway resolves upstream services using Kubernetes DNS:

# Service resolution pattern
{service-name}.{namespace}.svc.cluster.local:{port}

# Examples
iam-service.matih-control-plane.svc.cluster.local:8081
ai-service.matih-data-plane.svc.cluster.local:8000
query-engine.matih-data-plane.svc.cluster.local:8080

Kong's upstream health checks verify that backend services are responsive:

When a service is marked unhealthy, Kong removes it from the load balancer pool and stops routing traffic to it until it recovers.

Security Headers

The gateway adds security headers to all responses:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
Referrer-Policy: strict-origin-when-cross-origin

These headers are set at the gateway level as the first line of defense. Backend services in the Control Plane add complementary headers via the SecurityFilter, providing defense-in-depth.

CORS Configuration

The gateway handles Cross-Origin Resource Sharing (CORS) for all browser-based clients:

Access-Control-Allow-Origin: {configured origins}
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Request-ID,
                               X-Correlation-ID, X-Tenant-ID
Access-Control-Max-Age: 3600
Access-Control-Allow-Credentials: true

CORS origins are environment-specific:

• Development: http://localhost:3000 through http://localhost:3005
• Production: Configured per-tenant domains (e.g., https://acme.matih.ai)

WebSocket and SSE Support

The gateway supports two streaming protocols:

Server-Sent Events (SSE)

Used by the AI service for streaming chat responses:

Client --> GET /api/v1/ai/chat/stream
  Accept: text/event-stream

Gateway:
  - Validates JWT
  - Extracts tenant context
  - Proxies to ai-service:8000 with streaming enabled
  - Disables response buffering
  - Sets proxy_read_timeout to 300s for long conversations

WebSocket Upgrade

Used for real-time dashboard updates:

Client --> GET /api/v1/bi/ws
  Connection: Upgrade
  Upgrade: websocket

Gateway:
  - Validates JWT before upgrade
  - Upgrades connection
  - Proxies WebSocket frames bidirectionally
  - Maintains connection until client disconnects or timeout

Request Lifecycle Through the Gateway

A typical authenticated request flows through the gateway in the following order:

1. Request arrives at Kong (port 8080)
2. [Request Validation Plugin] Validate input, check for attacks
3. [JWT Claims Extraction Plugin] Validate JWT, extract tenant context
4. [Tenant Rate Limiting Plugin] Check rate limits for tenant
5. [Route Matching] Find upstream service based on URL path
6. [Upstream Health Check] Verify target service is healthy
7. [Proxy] Forward request with injected headers
8. [Response Processing] Add security headers, strip internal headers
9. Return response to client

Average latency added by the gateway: 2-5ms for authenticated requests, 1-2ms for public routes.

Monitoring and Observability

The gateway exports metrics via Prometheus:

These metrics power Grafana dashboards that show:

• Request volume and error rates per service
• Gateway latency breakdown (plugin processing vs. upstream response)
• Rate limit utilization by tenant tier
• Top endpoints by request volume

Related Sections

• Request Lifecycle -- Full end-to-end request flow through the gateway
• Security -- Authentication and authorization architecture
• Control Plane -- The api-gateway service details
• Kubernetes -- Gateway deployment and Helm configuration