Auth

Human authentication is WorkOS AuthKit; the portals (portal, portal-business) sign in through it. Machine/storefront auth (Vendure) is separate and intentionally retained (see decision record).

Organizations & roles

• Each tenant maps to a WorkOS organization. Provisioning mints one keyed on business.id (see Provisioning).
• Access is gated by org membership and role. Gates are strict — there is no silent member fallback; a missing owner role is fixed by the backfill-workos-owner-role.ts script, not by re-adding a shim.

Two allowlists (the common footgun)

WorkOS has two separate allowlists, and both must include each origin:

1. Redirect URIs — where AuthKit may return after login.
2. Allowed Origins — which web origins may initiate the flow.

Configuring only the first produces a silent /callback redirect loop. Add the origin to both for every environment (including localhost in dev).

Shared primitives

• @nexus/auth-client — shared WorkOS AuthKit React primitives.
• @nexus/workos-auth — server-side gates/roles helpers.

SSE scoped tokens (stoken)

Server-Sent Events streams (notifications, convergence) are authorized with a short-lived scoped token (stoken), not a long-lived ?token= query param (a security migration). The stoken is minted per stream and expires quickly. See the Glossary.