Two-tier RBAC¶
RG's authorization model is two-tier: every decision combines an organization-scope role with an optional per-cluster role override. Roles are defined against a resource-typed permission catalog, and the effective role is resolved per request, so a permission change takes effect on the next call with no stale-permission window. This is what delivers least privilege at fleet scale.
The two tiers¶
Authorization asks two questions and combines their answers. The first tier is the user's organization-scope role, which sets their baseline authority across the whole organization. The second tier is an optional per-cluster override, which adjusts that authority for a specific cluster — granting more on one cluster, less on another, or nothing different at all. The override is optional: where none is set, the organization role applies unchanged. Combining the two lets an organization express real-world authority precisely — a user who administers one region but only views another — without inventing a separate global role for every combination. Every authorization decision runs this combination; there is no path that consults only one tier.
Built-in roles¶
The platform ships four built-in roles spanning the common levels of authority.
| Role | Authority |
|---|---|
owner |
Full control of the organization, including roles, billing, and cluster lifecycle. |
administrator |
Manage devices, bridges, configuration, and users within scope; no organization-ownership actions. |
operator |
Operate devices — apply configuration, run actions, open native GUI sessions — without managing users or roles. |
viewer |
Read-only visibility into inventory, state, and history. |
These cover most needs directly, and each can serve as an organization-scope role, a per-cluster override, or both. They exist so that common deployments need no custom roles at all.
Custom roles and the permission catalog¶
Beyond the built-ins, an organization defines custom roles against a resource-typed permission catalog — a set of permissions organized by the kind of resource they act on (devices, bridges, configuration, roles, audit, and so on). A custom role is a selection of permissions from that catalog, which lets an organization express authority the built-in roles don't, such as "operate devices but never view audit" or "manage bridges only." Because the catalog is resource-typed, permissions compose predictably by resource kind rather than as an opaque flag list. Custom roles slot into the same two-tier model as built-ins: they can be an organization role or a per-cluster override.
Per-request resolution¶
Authorization is resolved per request, not cached into a session at sign-in. Application logic declares the permission an action requires, and the platform computes the user's effective role — organization role combined with any per-cluster override — at the moment of the request, then checks it against that declared permission. The consequence is that there is no stale-permission window: revoking or changing a role takes effect on the very next request, not whenever a token or cached grant happens to expire. This is what makes access changes trustworthy at scale — an administrator who removes a permission knows it is enforced immediately, everywhere it applies.
Payoffs and air-gapped behavior¶
Two-tier, per-request RBAC produces the properties large and multi-tenant operators need. Least privilege at scale because authority is scoped per cluster without role explosion. Separation of duties because operating a device and managing who may operate it are distinct permissions. Managed-service delegation because a provider can grant a customer scoped authority on a shared cluster. Per-customer scoping because overrides confine a user to specific clusters. On air-gapped clusters, RBAC behaves identically: the same organization roles and overrides are evaluated locally within the cluster against its local catalog, so an isolated site enforces the exact model a connected one does, with no dependence on the cloud to make a decision.