Platform

One gateway.
Every tenant, every API, every user.

The SOAJS gateway resolves the customer from the key, applies their package's ACL to the exact API being called and validates the user's token. Then it applies traffic policy and routes the call. Core services for users, tokens and tenants run behind it, and your services plug in with an SDK and a config file.

How it fits together

A multi-tenant, real-time product on SOAJS

Apps, a real-time server, background jobs and your own services all go through one gateway. Tenancy, ACL and tokens are decided there, once.

Swipe sideways to see the whole diagram.

Example architecture of a multi-tenant product on SOAJSClients call the SOAJS gateway over HTTPS with a tenant key and access token. The real-time socket server authenticates each connection through the gateway and sends every API call through the gateway pipeline. The gateway resolves the tenant, checks the package ACL, validates the OAuth token, applies URAC access and traffic policy, then routes to SOAJS core services or your own microservices. Scheduled jobs call the gateway with their own tenant key. AI agents connect over MCP to /soajs/mcp, see the APIs their key and user allow as tools, and each tool call goes through the same pipeline.ClientsMobile appsiOS · AndroidWeb portalscustomer & admin, as static UIsPartner integrationsserver-to-server API callsAI agentsMCP clients · assistants, copilotsAHTTPS · key + access_tokenEMCP · POST /soajs/mcpBWebSocketReal-time servere.g. Socket.IOauth: GET /soajs/aclemit('api') → gatewaySOAJS gatewaysoajs.controller · scale with replicas1External key → tenanttenant · application · package2Package ACLservice · version · API3OAuth tokenrestricted · device-bound4URAC user & tenantuser · groups · overrides5Trafficrate limit · cache · idempotency6Route via registryservice name + versionMongoDBregistry · tenants · products · ACLDScheduled jobs & other deploymentscron jobs and daemons call the gateway with their own tenant keyeach customer, region or network can be its own tenantSOAJS core servicesoauth · urac · multitenant · consoleCYour microservices · Node.js, Go, PythonAccountsonboarding · organizations · profilesProductcatalog · orders · paymentsMessagingchat · notifications · email & SMSPlatformfiles · analytics · reportingThird-party servicespayments, media, messaging
  1. API calls. Each client app has its own external key, tied to a tenant and a product package. Every request carries that key and the user's access token, and the gateway runs steps 1–6 before your code executes. Device-bound tokens also need the matching device-id header.
  2. Real-time. Your socket server doesn't need its own auth. It validates each connection's key and token with the gateway's /soajs/acl endpoint, then sends API calls through the same gateway pipeline as HTTPS traffic, so one ACL covers both.
  3. Service to service. Services call each other and the core services through SOAJS inter-service connections, with tenant and user context carried on each call. A service only declares extKeyRequired, oauth and urac in its config; it writes no authentication code.
  4. Jobs and deployments. Background jobs are clients too: they call the gateway with their own tenant key and get the same ACL. Model each customer, region or network as a tenant to keep their data and access apart.
  5. AI agents. Agents connect over MCP to /soajs/mcp with their own tenant key and a user's token. They see the APIs that key's package and that user allow as tools, and every tool call goes through steps 1–6 like any API call. MCP for AI agents

Connect Spaces runs this pattern in production: 23 microservices and a Socket.IO real-time layer behind one SOAJS gateway. Read the case study.

Tenants & keys

Sell the same services as different products

Every request carries a key. The key says which customer is calling and what they subscribed to.

Multitenancy guide →

  • Products and packages. A product groups services; each package inside it is a plan with its own ACL.
  • Tenants, applications and keys. A tenant subscribes to a package through an application, and each application gets its own external keys with an expiry date.
  • Key restrictions. Each key can carry IP allow and deny lists and device rules by browser and user agent.
  • Per-tenant behaviour. Service configuration and tenant profiles let one deployment behave differently for each customer.
  • Networks and memberships. Packages can be overridden per network, and user memberships are resolved per product.

Access control

ACL down to every API

The package ACL decides, per environment, service version, HTTP method and API, who may call what.

  • Three levels per API. Public, signed-in users, or only users in named groups.
  • Restricted mode. With apisPermission: "restricted", any API not listed is refused.
  • Overrides where you need them. An ACL on the application replaces the package ACL, and a user's groups can grant their own packages for the product.
  • One source of truth. /soajs/acl returns the ACL for a key and user, so socket servers and other tools apply the same rules.

Access control guide →

Pro package ACL · orders service v1
{
  "prod": {
    "orders": {
      "1": {
        "access": true,
        "apisPermission": "restricted",
        "get": {
          "apis": {
            "/catalog": { "access": false },
            "/reports": { "access": ["managers"] }
          }
        },
        "post": {
          "apis": { "/orders": { "access": true } }
        }
      }
    }
  }
}

/catalog is public, /orders needs a signed-in user, /reports needs themanagers group, and every other API is refused.

Identity & tokens

OAuth and users, built in

The oauth and urac services run behind the gateway like any other service; the gateway checks their tokens on every private API.

  • OAuth 2.0, per tenant. Access and refresh tokens, with the signed-in user and their groups forwarded to your service on req.soajs.urac.
  • Every login method. Username and password, LDAP, OpenAM, social providers, Azure AD, PIN, or phone number with a one-time code.
  • Users and groups. URAC manages users, groups, invitations and per-user access, separately for each tenant.
  • Restricted tokens. A signed-in mobile app can authorise a web app on another tenant and product without a new login, and the token only works where it was issued. How it works
  • Device-bound tokens. Tokens can be tied to a device ID that the gateway checks on refresh and on every private call. Details

MCP for AI agents

Your APIs as tools, with your rules

One endpoint, /soajs/mcp, turned on per environment in the registry.

MCP for AI agents →

  • Tools from what services already declare. SOAJS services describe their APIs from config.js; services built with the Node.js, Python or Go SDK from their Swagger or OpenAPI document.
  • Filtered per caller. An agent sees the APIs its key's package and its user's ACL allow; a restricted service shows only what its ACL lists.
  • Every call checked. A tool call is processed as the API call it stands for: key, OAuth, device binding, tenant access resolver, ACL, rate limiting, idempotency and caching.
  • Agents get their own key. Give agents an application, key and package of their own in the tenant to give them a narrower set than your apps.

Traffic

Policy at the edge

Configured in the registry or per service, enforced by the gateway before the call is routed.

Rate limiting · Caching · Idempotency

  • Rate limiting. By tenant, or by tenant and IP, with separate strategies for public and private APIs that services can override.
  • IP ban list. Blocked addresses never reach a service.
  • Response caching. GET responses cached per API with their own time-to-live, scoped per tenant or per user, in memory or MongoDB.
  • Idempotency. An Idempotency-Key header makes writes safe to retry: the gateway runs the request once and replays the stored response.
  • CORS. Origins and credentials set per environment.

Routing & operations

Find the service, keep it running

Two gateway builds share the same registry, keys and ACL model.

Node.js · Express 5Go · preview

Gateway reference →

  • Registry and discovery. Services are found through a MongoDB-backed registry and routed by name and version, with tenant and user context attached.
  • Cross-environment proxy. /soajs/proxy forwards a call to another environment's gateway with its own key.
  • Roaming between deployments. A user signed in on one deployment can reach services on another. The tenant and user context the first gateway verified travels with the call, and the receiving gateway accepts it only from gateway IPs it has whitelisted for that service.
  • Maintenance. Gateway-wide maintenance mode, and a maintenance port on the gateway and every service for readiness checks and registry reload.
  • Activity tracking. Last-seen per user, with triggers by service, method or API.
  • Safe logs. Error logs with sensitive values redacted.
  • Go build. The same gateway written in Go, released as 4.4.34. It answers as the Node.js gateway does, checked request by request, and reads the latest data schema only. Compare the two

Input validation

Inputs mapped and validated before your handler

IMFV: input mapping, formatting and validation, declared in the service config.

  • Sources in priority order. Read each input from query, body, params or headers, with defaults.
  • JSON-schema validation. Types, formats, objects and arrays, including custom formats.
  • Shared fields. Declare common inputs once and reuse them across a service's APIs.
  • Hardened parsing. Protection against ReDoS patterns and prototype pollution, with request size limits.

Console & marketplace

Run the whole platform from one place

A React web console backed by its own microservices.

  • Environments. Registry and configuration for each environment.
  • Customers and plans. Tenants, applications, keys, products, packages and their ACLs.
  • Marketplace. A catalog of every service, daemon, resource and static UI.
  • Code and infrastructure. Git repositories, cloud accounts and Kubernetes clusters.

SDKs

Bring your language

Services in any of these languages sit behind the same gateway, keys and ACL.

Node.js

The soajs framework plus the soajs.nodejs middleware for Express apps.

Node.js SDK

Go

soajs.golang middleware for Go HTTP services.

Go SDK

Python

soajs.python for FastAPI, Starlette, Flask and Django.

Python SDK

Deploy

Kubernetes, with Helm

From managed cloud clusters to air-gapped on-prem.

Helm · soa.json

  • Helm charts. One for the gateway and each core service, published as soajsorg/* images.
  • Deploy from source. A deployer image builds and runs your service inside the container.
  • Self-describing repos. A soa.json file declares whether a repo is a service, a daemon, a static UI, a config or a custom component. Resources and cron jobs are deployed through the marketplace.

See it on your own cluster

Install the gateway and core services with Helm, then put your first service behind it.