Auth And Workspace Model
Understand how authentication, authorization, and workspace scoping shape almost every API request in Noderax.
Auth And Workspace Model
Most operational endpoints require JWT bearer authentication and are guarded by workspace-aware authorization decisions.
Authentication
Noderax uses bearer token authentication for protected API surfaces. Swagger and the generated OpenAPI model treat this as the main authorization mechanism.
The browser usually authenticates through the web app session flow. The Next.js app holds the user session and proxies many operator-facing API requests through internal route handlers instead of sending browser requests directly to the API.
Direct API consumers use bearer authentication for protected endpoints. This is the primary model represented in the generated OpenAPI reference.
Before the platform is fully installed, setup and selected health routes must be callable without the usual installed-runtime operator session model.
Workspace scoping
Workspace context matters because nodes, events, metrics, tasks, packages, notifications, and most realtime events are scoped to a workspace.
Most “missing data” bugs are not transport bugs. They are workspace-scope mismatches: wrong workspace slug, missing membership, or a request/event bound to a different workspace than the operator expects.
Access layers
Public or setup-oriented exceptions
Some routes intentionally sit outside the usual installed-runtime auth flow, including:
- setup validation and setup install routes
- selected health routes
- certain public auth flows
Practical API implications
HTTP routes
Expect authenticated `/api/v1` routes for most installed-runtime operator actions, with selected health routes intentionally left outside the prefix.
Realtime
Realtime delivery is still workspace-scoped even after the websocket is authenticated. A connected socket must join the correct rooms to receive useful events.
Node-generated commands
Generated install commands and other operator-facing artifacts must use an externally reachable API origin, not an internal container hostname.