Gateway Overview

The API Gateway is the single ingress point for all HTTP traffic reaching the platform. It validates every request, decides whether authentication is required, routes the request to the correct backend service, and records a full audit trail. The gateway runs in front of each backend service (integration, notification, owner, user, admin) via dedicated gateway binaries (cmd/*-gateway).

What the Gateway Does

1. Reverse proxies requests to the appropriate backend service using httputil.ReverseProxy.
2. Authenticates requests by validating the Bearer JWT signature (supports standard, discover, and legacy integration secrets).
3. Authorizes requests against a per-endpoint permission list defined in the gateway config.
4. Marks public endpoints as auth-exempt (health checks, OAuth login, public blockchain utilities, webhooks).
5. Audits every request with masked credentials, correlation IDs, timing, and request/response bodies.
6. Cache-validates login-issued JWTs against Redis to support centralized revocation.

Middleware Pipeline

Requests flow through the following middleware in order:

#	Middleware	Purpose
1	SetStartTime	Records request start (UnixNano) for elapsed-time measurement
2	CorrelationID	Generates or forwards X-Correlation-ID for distributed tracing
3	BodyDump	Captures request and response bodies for audit
4	TargetHost	Resolves target service from X-Target-Server (or default)
5	MatchServiceEndpoint	Matches the request path/method to a configured endpoint
6	IntegrationPublicAndHost	Flags the endpoint as public/private and sets target host
7	IntegrationBearerJWT	Validates JWT signature using the correct secret
8	IntegrationJWTClaims	Parses claims, checks expiration, flags API vs. login tokens
9	IntegrationRedisClientToken	Verifies login token in Redis cache (revocation check)
10	IntegrationSetTargetHost	Finalises the upstream host for proxying
11	Proxy	Forwards the request with ReverseProxy.ServeHTTP

Public endpoints bypass steps 7–9 but still flow through audit (step 3).

Required Request Headers

Header	Required	Description
Authorization	For protected endpoints	Bearer <access_token>
X-Target-Server	Multi-service deployments only	Target service name (e.g. integration, notification). Defaults to the single-service gateway's binding when omitted.
X-Correlation-ID	Optional	Trace/correlation identifier; a UUID is generated when absent.

Public vs. Protected Endpoints

Endpoints marked public: true in the gateway's YAML configuration do not require an Authorization header. Typical public entries:

• OPTIONS ** — CORS preflight
• GET /v1/health, GET /v2/health, GET /health
• GET /swagger/*
• POST /v2/oauth/token — login (issues tokens)
• GET /v2/blockchain/gas-fee
• POST /v2/webhooks — receives webhook payloads (still Basic-auth-protected at the backend)

All other endpoints require a valid Bearer JWT.

JWT Types

The gateway accepts three classes of tokens, each signed with a different secret:

Type	Issued By	Used For
Standard user token	/v2/oauth/token	All user-facing API calls
Discover token	Platform discover service	Node-to-node /v1/discovers/** calls
Legacy integration token	Legacy issuer	Back-compat for pre-migration integrations

The correct secret is selected per endpoint based on the gateway's config.

Token Cache

Login tokens are validated against a Redis cache keyed by user sub + node aud. If the cache entry is missing or does not match, the request is rejected — this gives the platform a fast revocation path on logout or forced sign-out. API tokens and forgot-password tokens skip this check.

Audit Logging

Every request (public and protected) is logged asynchronously through the audit handler (contexts/gateway/api/v1/audit.go). The record includes:

• correlation_id, method, path, query, status_code, elapsed
• Masked headers (Authorization replaced with ***)
• Remote address, real IP
• Request / response bodies with password, token, and Authorization fields masked
• is_api flag (API client vs. interactive user)

Endpoints flagged doNotLog: true (e.g. noisy health probes) skip body persistence but still emit an info-level log line. Audit records land in MongoDB for long-term retention.

Operational Checklist

• Confirm X-Target-Server mapping is correct when running a multi-service gateway.
• Rotate JWT secrets simultaneously in the gateway and backend service; mismatches manifest as blanket 401s.
• Monitor audit volume — each request writes a document; noisy public endpoints should be marked doNotLog.
• When adding a new backend endpoint, remember to register it in the gateway YAML with the correct permissions and public flag — unregistered endpoints return 404 at the gateway even if the backend handles them.

Where the Gateway Does Not Enforce

The gateway is intentionally a thin layer. The following client-level guards are enforced by the integration backend middleware, not here:

• mTLS (require_certificate, cert_fingerprint) — verified against the NGINX-forwarded ssl-client-fingerprint header by the integration service.
• IP allowlist (allowed_ips).
• Rate limit (rate_limit.requests_per_second/minute/hour) — 429 with Retry-After and X-Ratelimit-* headers.
• Monthly usage quota (monthly_limit) — 429 with X-MonthlyLimit-* headers.

See Create Client for the client document shape and Usages / Score for how monthly quotas accrue.