API Gateway
The HTTP entry point: authentication, signing, access control and observability
Background
One gateway serves the end-user apps, the tenant/partner back office and later an external admin API. Each route needs a different combination of authentication, tenant resolution, access control and observability, and every downstream service needs to know who is calling for audit purposes.
Architecture
Client → Gin middleware chain (logging/recovery → tracing → metrics → domain/tenant resolution → token auth → account status → black/whitelist → IP policy) → handlers that validate input, check permissions and fan out to gRPC services → responses reshaped for each client. The auth middleware writes operator, IP, path, tenant and trace ID into outgoing gRPC metadata.
Key Highlights
Original middleware: token authentication with user-context injection, request-signature verification, multi-dimension black/whitelist, domain-to-tenant resolution, IP policy, structured logging with panic recovery, OpenTelemetry tracing and Prometheus metrics
Later additions: an account-status guard on all authenticated routes, per-platform domain switches, and operator/tenant/trace metadata attached to every downstream gRPC call
Hierarchical, field-level authorisation for the partner network: operators can only act down their own line, and sensitive fields (risk level, bound IP, password) have their own permissions
PII masking in admin responses; compensating rollback around multi-service account creation
Cross-service list filters resolved to ID sets and run in parallel
Key Implementations
Composable middleware chain
Each cross-cutting concern is its own Gin middleware, so route groups opt into exactly the policies they need.
Why: End-user, back-office and integration routes need different security; keeping concerns separate keeps handlers small.
Caller identity on every downstream call
After authentication, the middleware attaches operator ID, client IP, HTTP path, tenant and trace ID as outgoing gRPC metadata.
Why: Any downstream service can then record an attributable audit event or a trace without re-deriving who the caller is.
Result: This became the basis of the platform-wide audit trail (see Audit Log Service).
Hierarchical authorisation
A permission check that lets the platform admin act anywhere, keeps members out, and only lets other operators act on accounts below them in the partner tree. Separate rules cover master and sub-accounts and individual sensitive fields.
Why: In a multi-level partner network, "can edit users" is not enough; the question is whose users.
Technical Decisions
| Technical Decisions | Chosen | Alternative | Reason |
|---|---|---|---|
| Framework | Gin | go-zero REST | Gin's middleware chain gives fine-grained per-route-group control, which matters more at the edge than code generation. |
| Where to resolve the caller | Once at the gateway, propagated as gRPC metadata | Each service re-validates the token | One validation per request, and a single consistent identity for logs, traces and audit events. |