How the workspace gateway (API) works

What the gateway is

Almost every StretchSuite app — Shop, Social, Mail, CRM, Sheets, and more — needs to read and write data from the platform backend. They all do it through one shared, secure pattern called the workspace gateway. Understanding it explains why connections stay private between organizations, why you rarely juggle API keys yourself, and where to look when something can't load.

You don't have to operate the gateway — it's built in. But knowing the model helps you reason about permissions, tenancy, and errors.

The flow, step by step

1. Your browser loads an app in your workspace (say, StretchShop).
2. The app makes a same-origin request to your workspace — a path like /api/gw/shop/client/orders. Notice it calls your own workspace, not the backend directly.
3. Your workspace server receives that request and reads your session cookie. From the (cryptographically signed) session it determines who you are and which organization you're currently acting in — and it validates that org against your real membership list. This identity is derived on the server; a browser cannot fake it.
4. The server forwards the request to the platform backend (api.stretchsuite.ca/api/v1), attaching a shared gateway secret plus headers identifying your org, user, and role.
5. The backend trusts the request because of the secret and serves only your organization's data.
6. The response flows back through the gateway to your app.

The two things that never reach the browser: the gateway secret and the authoritative org identity. That's the whole security story in one sentence.

Why this design matters to you

• Tenant isolation is enforced server-side. Because your organization is derived from your validated session — not from a URL parameter or anything the browser sends — one tenant cannot request another tenant's data by tampering with a request. This is why your Shop orders, CRM contacts, and Social connections stay yours.
• You don't manage raw secrets for in-app usage. For everyday use inside the workspace, the gateway handles authentication invisibly. You authenticate by being logged in.
• Access follows your role. Your workspace role travels with each request, so the backend can allow or deny actions based on your permissions.
• Only safe surfaces are exposed. The gateway only proxies organization-scoped client endpoints (each app's /client/* surface, plus specific managed surfaces like StretchWP's workspace endpoints). Administrative or cross-tenant endpoints are not reachable this way.

A realistic example

You open StretchSocial and it shows your connected channels:

1. The Social app requests /api/gw/social/client/connections from your workspace.
2. Your workspace server confirms your session, sees you're acting in the Payne Coaching organization, and forwards the request to the backend with the gateway secret and your org/user/role headers.
3. The backend returns only Payne Coaching's social connections.
4. If you switch to a different organization in the workspace switcher and reload, the exact same code path now returns that org's connections instead — because the org came from your session, not from the app.

What can go wrong (and why)

"Sign in to your workspace to continue" / 401 — your session is missing, expired, or you haven't selected an organization. Sign in again and pick a workspace. The gateway fails closed: no valid session means no data.

"Gateway path not allowed" / 404 — a request targeted an endpoint the gateway doesn't expose. Only org-scoped client surfaces are proxiable; this usually indicates a bug or an unsupported action, not a permissions issue you can fix by changing settings.

"Workspace gateway is not configured" / 503 — the gateway secret isn't set in that environment; this is an operational/config issue for the platform, not something you resolve as a user.

An app loads empty — often the backend returned no rows for your org (you genuinely have no data yet), not an auth failure. Distinguish "empty" from "error" — the app usually says which.

Tips

• If an app won't load data, re-confirm your active workspace first. Most "missing data" reports are actually "looking at the wrong organization."
• The gateway is per-organization. Data and connections don't bleed across the organizations you belong to; switch context deliberately.
• For programmatic/external access (outside the browser), you need proper API credentials rather than the in-browser session — see API access, tokens, and StretchDev.

FAQ

Can I call the backend API directly from my own code? Not through the browser gateway — that path requires a workspace session cookie. For server-to-server or external automation, use dedicated API access.

Why can't I hit another organization's data if I'm an admin of both? You can — by switching your active workspace to that organization. The gateway always serves the currently selected org.

Is my data encrypted in transit? Yes; requests travel over HTTPS, and the sensitive gateway secret never leaves the server.