Skip to main content

​
Overview

Port: 4000 The Gateway is the central entry point for all frontend requests. It routes to backend services via HTTP proxy and is completely stateless — JWT signature is verified in middleware (verifyJwt) and context is passed via headers to downstream services.

​
Proxy Routes

The public API /v1/* routes (e.g. POST /v1/agents:from-url, GET /v1/agents/builds/:buildId, POST /v1/chat) use API-key authentication (Bearer API key, validated via the auth service) rather than JWT, and proxy to the bot service’s agent-build and chat routes.
When adding new backend routes, you must add the corresponding proxy route in services/gateway/src/routes/proxy.ts. Without this, the frontend cannot reach your new endpoint.

​
Auth Middleware

The gateway handles JWT authentication for all proxied requests:
1

Extract Token

JWT is extracted from the Authorization: Bearer header or the access_token cookie.
2

Verify Signature

The gateway verifies the JWT signature with the shared secret:
3

Validate Membership

Validates that the user has at least one organization membership.
4

Attach Auth Context

Sets request.auth with: userId, organizationId, email, platformRole, orgRole.
5

Forward Headers

Forwards auth context to downstream services as headers:
  • user-id
  • organization-id
  • user-email
  • x-platform-role
  • x-org-role
The gateway verifies the JWT signature; downstream services trust forwarded headers. The gateway is the trust boundary — it is the only public ingress, and downstream service ports (4001–4006) are not exposed to the internet.

​
Plugins

​
Configuration Variables

​
Critical Patterns

The gateway follows AUTHENTICATION_PATTERN.md — the JWT signature is verified with the shared secret (verifyJwt(token, config.JWT_SECRET)). Downstream services trust requests that come through the gateway.
Auth context is passed via HTTP headers to downstream services, not via cookies. Services read request.user from their own JWT middleware that parses these headers.
Custom parser passes raw buffer for multipart uploads. The realtime-audio service has a 50MB upload limit for voice samples.
When a downstream service is unavailable, the gateway returns 503 with a descriptive error message.
Headers like host, connection, and transfer-encoding are filtered before forwarding to downstream services.