Id RFC 008 api gateway

RFC-008 — API Gateway

*tatus:*Draft
*ate:*20260408
*uthor:*Koder Team
*epends on:*RFC-001

Summary

The API Gateway is a lightweight Go reverse proxy that sits in front of all Koder ID microservices. It handles routing, tenant resolution, rate limiting, CORS, and TLS termination. It exposes a single HTTPS endpoint to the outside world.

Why a Custom Gateway

*implicity:*a thin Go proxy (~500 lines) is easier to maintain than configuring Envoy/Traefik for our specific routing needs
*enant resolution:*custom middleware that resolves tenant from domain/header before routing
*ingle binary:*fits the deployment model (one binary, no YAML config for external tools)
*o external dependency:*the gateway ships as part of Koder ID

If operational complexity grows (canary deployments, circuit breaking, etc.), we can swap for Envoy later — the services behind it don't change.

Architecture

Internet
    │
    │ HTTPS (443)
    ▼
┌──────────────────────────────────────────┐
│              API Gateway                  │
│                                          │
│  ┌─────────────┐  ┌──────────────────┐   │
│  │ TLS Termina │  │ Tenant Resolver  │   │
│  │ tion        │  │ (domain/header)  │   │
│  └─────────────┘  └──────────────────┘   │
│                                          │
│  ┌─────────────┐  ┌──────────────────┐   │
│  │ Rate Limiter│  │    CORS          │   │
│  └─────────────┘  └──────────────────┘   │
│                                          │
│  ┌──────────────────────────────────┐    │
│  │         Router / Proxy           │    │
│  └──────────────────────────────────┘    │
└────┬────────┬────────┬────────┬─────┬────┘
     │        │        │        │     │
     ▼        ▼        ▼        ▼     ▼
 Identity   Auth    OAuth2  Session  Admin
  :4001     :4002   :4003    :4004   :4005

Routing Rules

Path Pattern	Target Service	Notes
`v1users