Browser to Gateway
This flow covers the initial request path from a browser or API client through the Kong API Gateway to a backend service. Every request to the MATIH Platform traverses this path, making it the most frequently executed flow in the system.
Authentication Flow
Before any data requests, users must authenticate to obtain a JWT token pair:
Browser Kong Gateway IAM Service
| | |
| POST /api/v1/auth/login | |
| (email, password) | |
|------------------------------->| |
| | (public route, no JWT) |
| | Forward to iam-service |
| |-------------------------->|
| | |
| | Verify credentials
| | Load user + roles
| | Resolve tenant_id
| | Generate JWT pair
| | |
| | {accessToken, |
| | refreshToken, |
| | expiresIn: 900} |
| |<--------------------------|
| 200 OK | |
| (token pair) | |
|<-------------------------------| |Authenticated Request Flow
Every subsequent request includes the JWT token and passes through the gateway:
Browser Kong Gateway Backend Service
| | |
| GET /api/v1/bi/dashboards | |
| Authorization: Bearer <JWT> | |
|------------------------------->| |
| | |
| 1. Validate JWT signature |
| 2. Check token expiration |
| 3. Extract tenant_id, user_id, roles |
| 4. Check rate limit for tenant |
| 5. Match route to service |
| 6. Inject X-Tenant-ID header |
| 7. Inject X-Request-ID header |
| | |
| | Forward with headers |
| |-------------------------->|
| | |
| | SecurityFilter |
| | JwtAuthFilter |
| | TenantCtxFilter |
| | Controller |
| | Service layer |
| | Repository |
| | |
| | Response |
| |<--------------------------|
| 200 OK | |
| (response body) | |
|<-------------------------------| |Gateway Processing Steps
| Step | Action | Failure Response |
|---|---|---|
| 1 | Validate input (headers, body size) | 400 Bad Request |
| 2 | Verify JWT signature (HMAC-SHA256) | 401 Unauthorized |
| 3 | Check token expiration | 401 Unauthorized |
| 4 | Check per-tenant rate limit | 429 Too Many Requests |
| 5 | Match URL path to service route | 404 Not Found |
| 6 | Inject tenant context headers | -- (internal) |
| 7 | Forward to backend service | 502 Bad Gateway (if service unreachable) |
Token Refresh
When the access token expires (after 15 minutes), the client refreshes it:
Browser Kong Gateway IAM Service
| | |
| POST /api/v1/auth/refresh | |
| (refreshToken in body) | |
|------------------------------->| |
| |-------------------------->|
| | |
| | Validate refresh |
| | Generate new pair |
| | |
| |<--------------------------|
| 200 OK | |
| (new accessToken, | |
| new refreshToken) | |
|<-------------------------------| |Timing Breakdown
| Step | Typical Duration |
|---|---|
| Network latency (browser to gateway) | 1-50ms |
| Gateway JWT validation | 1-2ms |
| Gateway rate limit check | 1-2ms |
| Gateway routing | less than 1ms |
| Network latency (gateway to service) | less than 1ms (in-cluster) |
| Service filter chain | 2-5ms |
| Total gateway overhead | 5-10ms |
WebSocket Upgrade
For AI streaming responses, the browser establishes a WebSocket connection:
Browser --> Kong Gateway --> AI Service
|
| HTTP Upgrade: websocket
| Sec-WebSocket-Protocol: matih-v1
|
v
WebSocket connection established
|
| Send: {"message": "What was revenue?"}
| Receive: {"token": "Revenue", "index": 0}
| Receive: {"token": " was", "index": 1}
| ...
| Receive: {"done": true, "sql": "SELECT ..."}Related Pages
- Query Flow -- Data query execution path
- Agent Flow -- AI agent processing path
- API Design: Authentication -- Authentication details