Workspaces and roles: how OpsAPI keeps tenants apart

Every business table in OpsAPI carries a namespace_id. A namespace is what the dashboard calls a workspace: one tenant, with its own members, roles, settings and data. Many workspaces share one deployment and one database. This note explains how a request is bound to exactly one of them, how roles decide what a member may do, and which controls are real boundaries.

Resolving the workspace

NamespaceMiddleware.requireNamespace in middleware/namespace.lua runs after authentication. It looks for the workspace in a fixed order and then checks that this user may use it:

-- middleware/namespace.lua: priority 1 is the header
local header_id = self.req.headers["x-namespace-id"]
if header_id and header_id ~= "" then return header_id end
local header_slug = self.req.headers["x-namespace-slug"]
if header_slug and header_slug ~= "" then return header_slug end
-- priority 2: the JWT's namespace (uuid, else slug); priority 3: the subdomain

Once it passes, the handler can rely on self.namespace, self.namespace_permissions, self.is_namespace_owner and self.is_platform_admin. It also stores ngx.ctx.namespace_id so the activity log attributes the request to the workspace.

API keys

An API key (opsk_…) is bound to exactly one workspace and has no membership row. Its workspace comes from the key itself and its scopes act as its permissions. Sending a namespace header that doesn't match the key's own workspace is refused with 403, so a key can never reach another tenant. Keys are never owners or platform admins.

Roles and permissions

Permissions are a map of module to a list of actions: read, create, update, delete, or manage, which means all of them. A member's effective permissions are the union of their roles in that workspace. A route asks for one pair:

for _, perm in ipairs(module_perms) do
    if perm == action or perm == "manage" then
        has_permission = true
        break
    end
end

New workspaces are seeded with default roles: owner with manage on every module, admin with manage on everything except namespace, which is read, and member with nothing until someone grants it. Owners and admins can add their own roles in the dashboard's role editor, for example a read-only viewer with read on every module.

Owners and platform admins

The three access layers

Teams often ask for "this tenant should only have modules X and Y". OpsAPI has three mechanisms that look similar from the dashboard but behave very differently at the API:

PROJECT_CODE is an environment variable of the whole process, so two workspaces in the same deployment can't have different API-reachable module sets. To give a tenant a hard limit that holds for its owner too, run it in its own deployment and database with a narrower PROJECT_CODE. The per-workspace namespaces.project_code column only filters the menu and seeds the default roles' modules; it is never checked at request time. Billing entitlements are metadata and are not a request-time gate either.

Status codes you'll see

Rules for module authors

1. Scope every query by namespace_id. The middleware sets the workspace; it doesn't rewrite your SQL.
2. Re-check ownership on read, update and delete. Load the row, compare its namespace_id with self.namespace.id, and refuse if they differ.
3. Gate writes with requirePermission and register the module's RBAC entry under PROJECT_MODULES in helper/project-config.lua so it appears in the role editor.
4. Never take namespace_id from the request body. Use the one the middleware resolved.
5. Index tenant tables on namespace_id first, because every query filters on it.