Roles & Permissions

Mental model

This page is catalog + definitions only.

from outlabs_auth.routers import get_roles_router, get_permissions_router

app.include_router(get_roles_router(auth, prefix="/v1/roles"))
app.include_router(get_permissions_router(auth, prefix="/v1/permissions"))

Permissions catalog (/v1/permissions)

Schemas: PermissionResponse, PermissionCreateRequest, PermissionUpdateRequest, PermissionCheckRequest / PermissionCheckResponse (has_all_permissions, results map).

Without entity_id, /me and /user/{id} return the historical aggregate (the union across contexts, *:* for superusers). With entity_id they return the catalog permissions held at that entity — direct grants there plus _tree / _all grants inherited from ancestors — the same semantics as POST /check. Gate entity-level UI actions on the entity-context set.

For effective permissions with sources (role vs membership), use GET /v1/users/{id}/permissions on the users router.

ABAC condition groups/conditions also hang off /{permission_id}/… when you use ABAC — same pattern as roles below.

The catalog is shared by every tenant. On EnterpriseRBAC with enforce_user_scope (the default), creating, updating or deleting a permission, and every write to its conditions or condition groups, needs a global actor — a superuser, a holder of a direct system-wide role, a service token or an unanchored integration principal. A tenant-scoped holder of permission:* gets 403 (DD-061). Reads are unchanged.

System definitions

is_system (permissions) and is_system_role (roles) mark the library-owned catalog. System definitions are immutable once created — no update, re-tagging, condition edits, or delete — so the HTTP API refuses to mint them: POST /v1/permissions/ rejects is_system=true, and RoleCreateRequest has no is_system_role field at all. They come from two places only:

• seed_system_records(...) (outlabs_auth.bootstrap), which seeds the library's permission catalog (SYSTEM_PERMISSION_CATALOG, overridable via its permission_catalog parameter) at startup, idempotently.
• Host code calling the services directly (permission_service. create_permission(..., is_system=True) / role_service.create_role(..., is_system_role=True)) — creation-time tags, permission_names, and entity_type_permissions all work there; immutability begins after the row exists.

Rationale and history: DD-060 in docs/DESIGN_DECISIONS.md.

Roles (/v1/roles)

CRUD and permission sets

Enterprise helper

Role response fields worth knowing

RoleResponse includes: name, display_name, permissions[], is_system_role, is_global, status, optional root_entity_id / scope_entity_id, scope (entity_only | hierarchy), assignable_at_types[], is_auto_assigned.

Enterprise tips:

• Non-global actors only manage roles in their trees; system-wide roles they cannot touch → 403; out-of-tree → 404. A personal API key carries its owner's tenant scope (narrowed to its anchor when it has one), never global scope on its own (DD-061)
• Writes to an entity-local role (create with scope_entity_id, update, delete, permission and ABAC condition changes) also need its scope entity in the tree of a non-global actor's own root (403 otherwise, DD-061 decision 17): a role seen only through a membership left in another tenant's tree by an earlier cross-root move is read-only, and unrooted legacy administrators change no entity-local roles
• In an entity-context check a role assigned directly to a user follows the same reach as a membership role: an org-scoped role only inside its own organization's tree, an entity-local role only inside its scope, system-wide roles everywhere (DD-054, DD-061)
• SimpleRBAC treats list/create visibility as effectively global
• assignable_at_types limits which entity types may receive the role; an empty list means assignable everywhere, so clearing it counts as widening
• is_auto_assigned can auto-apply on membership create/update

ABAC on roles (when enabled)

Under /{role_id}/condition-groups and /{role_id}/conditions — CRUD with role:read / role:update. Walkthrough: ABAC.

Simple vs Enterprise

Suggested host flow

1. Seed or create permissions (resource:action).
2. Create roles and attach permission lists (delegation check applies).
3. Simple: POST /v1/users/{id}/roles.
   Enterprise: POST /v1/memberships/ with role_ids; use GET /v1/roles/entity/{entity_id} in the UI.
4. Gate product UI with POST /v1/permissions/check (and entity_id when needed).
5. Optional attribute conditions: ABAC.

Related

• Routers & Prefixes
• User Management API
• ABAC
• Entities
• Entity Memberships
• Core Authorization Concepts