API Gateway Service (gateway-service)

The gateway-service is the entry point for all external traffic. It acts as an edge router, handling security and rate-limiting.

It is implemented with Spring Cloud Gateway and exposes the public HTTP ingress port for the platform. Downstream services are addressed through Eureka service discovery using lb:// routes, so callers do not connect directly to client-service or sms-router-service.

Runtime Responsibilities

The gateway is responsible for:

• Routing external HTTP requests to the correct backend service.
• Validating bearer-token requests before they reach protected APIs.
• Enriching authenticated requests with client/user identity headers.
• Allowing admin and internal routes to pass through to downstream X-Admin-API-Key validation.
• Applying gateway-level HTTP client, body buffering, and CORS behavior.

Stateless Validation

The gateway does not store session state locally. It validates token existence through Redis, where active sessions are stored by token key.

This keeps each gateway instance horizontally scalable: any instance can process a request as long as it has the shared JWT secret and access to the same Redis session database.

Redis Token Verification

1. Reads incoming bearer tokens: Authorization: Bearer <token>.
2. Validates the JWT signature using jwt.secret.key.
3. Queries Redis for key sms:token:{token}.
4. If the key is missing, expired, or the session payload cannot be parsed, rejects the request with 401 Unauthorized.

Redis connectivity is configured through redis.host, redis.port, redis.password, redis.database.index, and Redis connection pool settings. See Gateway Service Configuration for deployment values.

Header Forwarding

Once authenticated, the gateway extracts user metadata from the session JSON and forwards it to downstream services as HTTP headers:

Header	Description
X-Client-Id	Unique organization identifier.
X-User-Id	Unique client-user identifier.
X-Username	The client-user's username.
X-Status	Active status of the user profile.

Downstream services rely on these headers as the trusted identity context for requests that already passed gateway authentication.

Path Exclusion

Following path segments are excluded from Bearer token verification:

• /auth/login
• /auth/refresh
• /auth/logout
• /actuator
• /admin/
• /internal/

Note that, to access /admin/ or /internal/, you need to set the X-Admin-API-Key header.

Ingress Routing

The gateway uses Spring Cloud Gateway path predicates to send traffic to backend services:

Request Path	Target Service	Purpose
/auth/**	client-service	Login, token refresh, and logout.
/api/sms/**	sms-router-service	Direct SMS submission APIs.
/api/campaigns/**	sms-router-service	Campaign submission and campaign operations.
/api/**	client-service	General client-facing APIs not matched by more specific routes.
/admin/sms-config/**	sms-router-service	Operator SMS routing and carrier configuration.
/admin/clients/**	client-service	Client onboarding and balance administration.
/admin/reports/**	client-service	Client reporting APIs.
/internal/clients/**	client-service	Internal ledger and client service operations.

Admin and internal paths are intentionally excluded from bearer-token validation at the gateway because they are protected by X-Admin-API-Key in the receiving services.

HTTP and Browser Access

The gateway is configured to support large forwarded request bodies, including bulk campaign CSV uploads, using spring.codec.max-in-memory-size.

For browser clients, CORS allows local dashboard origins in development and accepts the authentication headers used by the platform:

• Authorization
• Content-Type
• X-Admin-API-Key

The gateway HTTP client also defines downstream connection and response timeouts so slow backend calls fail predictably instead of hanging indefinitely.

Service Dependencies

The gateway depends on:

Dependency	Usage
Redis	Validates active token sessions using sms:token:{token} keys.
discovery-service	Resolves lb://client-service and lb://sms-router-service routes.
client-service	Handles authentication, client administration, reports, and internal client operations.
sms-router-service	Handles SMS submission, campaign APIs, and SMS configuration administration.