Capablio

Handbook

ADR-001: Tenancy, session, and capability model

Status: accepted Date: 2026-07-17 Feature: CAP-FOUND-001

Updated

Context

Capablio serves multiple tenants from one deployment. Users may be tenant members or platform operators. Job titles alone do not determine access — capabilities do.

Decision

  1. Tenant isolation: Every user record has tenant_id. API handlers call assert_same_tenant() unless operator support mode is explicitly scoped via X-Forge360-Tenant-Id with audit.
  2. Session: Stateless bearer tokens (hashed in DB). No cookie session for API. UI stores token in sessionStorage.
  3. Capabilities: Expose manage_directory, manage_surveys, view_completion from /api/me. UI gates features on capabilities, not role labels.
  4. Operator boundary: is_operator grants control-plane routes only; no plaintext feedback in ordinary operator UI.

Consequences

  • New workspaces (07–11) must use capability checks from /api/me.
  • SCIM and SSO add identity sources but do not bypass capability matrix.
  • Child-tenant AFF features use existing parent_tenant_id model.

Alternatives rejected

  • Job-title-only RBAC (too coarse; fixture shows admin without manage_surveys).
  • Embedding operator inside tenant admin console (violates separation).