Routes
Every request on the gateway port whose path starts with a service name goes to that service. See Request URL. The routes on this page are answered by the gateway itself.
Gateway port
Section titled “Gateway port”| Route | Method | Description |
|---|---|---|
/soajs/acl |
any | The ACL of the calling key and user. |
/soajs/mcp |
POST |
The MCP endpoint for AI agents. Off unless enabled. |
/soajs/proxy |
any | Forwards a call to a URL, or to the gateway of another environment. |
/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server/... |
GET |
MCP sign-in discovery documents, when mcp.auth is set. |
/favicon.ico |
GET |
The favicon. |
/soajs/acl
Section titled “/soajs/acl”Returns what the caller may call. Front ends use it to show only the screens a user can reach.
Send the external key in the key header; without it the gateway answers 132. Send an access_token to get the user’s ACL instead of the package’s.
curl -H "key: <external key>" "http://localhost:4000/soajs/acl?access_token=<token>"{ "acl": {"orders": {"1": {"access": true, "apisPermission": "restricted", "get": {"apis": {"/orders": {}}}}}}, "finalACL": {"orders": {"version": "1", "get": ["/orders"]}}, "packages": ["SHOP_USER"], "urac": {"_id": "<user id>"}, "tenant": {"id": "<tenant id>", "name": "Shop", "code": "SHOP", "type": "product"}}The answer is the object itself, not wrapped in result and data.
| Field | Description |
|---|---|
acl |
The ACL as stored: from the user’s packages with a token, else from the key’s package. |
finalACL |
Per service, the latest version the caller may use and, for restricted services, the allowed APIs per method. |
packages |
The packages the ACL was built from. |
urac |
The user’s _id, with a token. |
tenant |
The key’s tenant. |
The key, OAuth and user checks run as for any call. The route has no ACL of its own.
/soajs/mcp
Section titled “/soajs/mcp”The MCP endpoint. AI agents see the APIs their caller may use as tools, and a tool call is processed as the API call it stands for. It answers 404 until mcp.enabled is true in the custom registry.
See MCP for AI agents and the mcp key.
/soajs/proxy
Section titled “/soajs/proxy”Forwards the request to the route given in the proxyRoute query parameter, URL-encoded. The method, headers and body are forwarded, and the answer is streamed back.
| Parameter | Required | Description |
|---|---|---|
proxyRoute |
yes | Without __env: a full URL. With __env: a gateway route, /<service>/<path>. |
__env |
no | Code of another environment. Also read from the __env header. |
extKey |
no | External key to use in that environment. |
tCode |
no | Code of a tenant. The gateway uses the tenant’s key for that environment. Defaults to the calling key’s tenant. |
With __env, the gateway loads the other environment’s registry and sends the call to its public address, protocol://[apiPrefix.]domain:port from the environment record. The key is the first of:
extKey, when given;- the key of
tCode’s tenant for that environment, with dashboard access; - none.
curl -H "key: <external key>" \ "http://localhost:4000/soajs/proxy?__env=STG&proxyRoute=%2Forders%2Forders"The external key is optional on this route. When it is sent, it is checked as for any call. The ACL and OAuth checks do not run here. The gateway of the other environment runs them.
/proxy/redirect is the older name of this route. The Node.js gateway still answers it and logs that it is deprecated. The Go gateway does not.
| Code | Meaning |
|---|---|
135 |
The call failed, or proxyRoute is not a valid URL. |
139 |
No tenant found for tCode. |
207 |
The other environment has no registry. |
208 |
The other environment has no protocol, domain or port. |
Maintenance port
Section titled “Maintenance port”The maintenance server listens on the gateway port plus serviceConfig.ports.maintenanceInc (5000 by default). Keep it inside the cluster: it has no key or token check.
| Route | Method | Description |
|---|---|---|
/heartbeat |
GET |
Answers when the gateway is up. Use it as the liveness and readiness probe. Any path not listed here answers the same. |
/reloadRegistry |
GET |
Reloads the environment registry and the custom registry. |
/loadProvision |
GET |
Reloads tenants, keys and packages. |
/awarenessStat |
GET |
The services the gateway knows, with their hosts and health. |
/getRegistry |
GET |
The registry of one service. Services call it at startup, at the address they get in SOAJS_REGISTRY_API. |
/register |
POST |
A service registers its host. Used without SOAJS_DEPLOY_HA only. |
/cache/invalidate |
POST |
Removes cached GET answers a service knows are out of date. Needs the mongo cache model. |
/schemaProblems |
GET |
Go gateway 4.4.32+ only. The problems found in the data the gateway read: collection, document _id, location, rule and what the gateway did (read as Node.js, left out a piece, skipped the document, fell back to the key’s package). Locations only, never values. ?collection= filters. See How Go reads imperfect data. |
/getRegistry
Section titled “/getRegistry”| Parameter | Description |
|---|---|
env |
Environment code. |
serviceName |
The service asking. |
type |
service (default), daemon or mdaemon. |
The answer holds the environment’s public address, its serviceConfig without cors (and without oauth, except for the oauth service), the core databases, the custom registry, the resources, the gateway’s entry and the asking service’s own entry.
/cache/invalidate
Section titled “/cache/invalidate”curl -X POST http://localhost:5000/cache/invalidate \ -H "Content-Type: application/json" \ -d '{"tenant": "<tenant id>", "service": "catalog", "api": "GET /products"}'The answer gives the number of entries removed. See Invalidation for the fields.
Reload after a change
Section titled “Reload after a change”Changes made in the console reach the gateway on the next registry load. To apply them at once, call each gateway instance:
curl http://<gateway pod>:5000/reloadRegistry # environment record, custom registrycurl http://<gateway pod>:5000/loadProvision # tenants, keys, packagesEvery service’s maintenance port
Section titled “Every service’s maintenance port”Each SOAJS service has its own maintenance port, with at least /heartbeat, /reloadRegistry and /loadProvision. From soajs 4.1.24 it also has /mcp/tools, which describes its APIs for the MCP endpoint. Which port that is depends on the environment and how the service runs: see Service ports.
