Capablio

Handbook

Role, permission, scope, and data-visibility model

Navigation roles are not authorization. Every protected operation must evaluate:

Updated

Principle

Navigation roles are not authorization. Every protected operation must evaluate:

actor + tenant + role assignment + organizational scope + resource + action + data class + policy + time

Client-side hiding is a usability feature only. Authorization and tenant isolation are enforced server-side and tested with negative cases.

Role Typical scope Primary purpose
Platform owner / global admin Cross-tenant Operate SaaS, plans, regions, catalog, incidents, and audited support
Platform support Cross-tenant but case-bound Diagnose tenant issues under approved, time-limited access
Platform content publisher Global catalog Publish global frameworks, packs, translations, and releases
Tenant owner One tenant Legal/commercial owner; full tenant configuration except platform-only controls
Tenant admin One tenant Organization, identity, security, integrations, content, and programs
Billing admin One tenant Subscription, invoices, usage, and billing contacts only
Security admin One tenant SSO, SCIM, domains, retention, keys, audit, and security settings
HR admin Tenant or assigned org scope Feedback programs, campaign operations, completion, and authorized analytics
HR business partner One or more org subtrees HR operations limited to assigned population and policies
Manager Team and permitted descendants Team tasks, nominations, development conversations, and shared actions
User / subject Self Tasks, feedback, results, PDP, privacy, and account
Rater / reviewer Assigned requests Complete specific feedback requests only
External rater Token or authenticated invite Complete assigned external feedback only
Auditor Read-only defined scope Review configuration and audit evidence without editing or plaintext feedback

A person may hold multiple roles. Each role assignment has tenant, scope, effective start/end, source, and audit history.

Permission model

Represent permissions as resource/action pairs with scope conditions, for example:

program:create
program:publish
campaign:manage
campaign:view_completion
response:submit
response:view_self
response:view_aggregate
comment:view_aggregate
pdp:view_self
pdp:view_shared
pdp:coach
question:author_tenant
question:publish_global
identity:manage
security:manage_sso
support:request_access
support:approve_access

Avoid broad flags such as is_admin as the only authorization control.

Data classes

Class Examples Default visibility
Public Marketing pages, public docs Anyone
Tenant configuration Branding, programs, org units, integrations Authorized tenant roles
Directory personal data Name, email, manager, org unit Scoped administrators and required workflow actors
Participation metadata Invited, started, completed, reminder state HR/admin/manager according to scope; no answers
Individual rating responses Item answers tied to respondent Subject through aggregation; limited operational access; never routine manager/HR plaintext
Qualitative comments Free text, potentially identifying Aggregated and redacted according to threshold/policy
Aggregate reports Relationship-group results Subject and explicitly authorized viewers after thresholds
PDP private Goals, reflections, notes Subject only by default
PDP shared Selected goals/actions Subject plus chosen coach/manager according to policy
Security secrets Keys, tokens, SSO secrets Dedicated secret stores; never displayed after creation
Audit data Administrative and security events Security/admin/auditor by scope
Support diagnostics Correlation IDs, job state, sanitized logs Platform support under case-bound access

Visibility defaults

  • HR sees participation and completion but not raw answers.
  • Managers do not automatically see a direct report’s full report or private PDP.
  • Individuals control sharing of private goals unless tenant policy clearly establishes another lawful model.
  • Global admins see tenant health and metadata, not plaintext feedback.
  • External raters see only the invitation, privacy notice, assigned questions, and completion confirmation.
  • Small relationship groups are suppressed according to configurable thresholds.
  • A single manager rating may be visible as a distinct relationship only when the program explicitly states this and the participant is informed.

Encryption and recovery modes

The current prototype uses client-side envelope encryption. Enterprise uplift should define supported policy modes instead of presenting one irreversible workflow as universal:

  1. Subject-private mode — Subject-controlled decryption; no tenant recovery. Strong privacy, with explicit unrecoverable-loss risk.
  2. Tenant-recovery mode — A tenant-approved recovery mechanism using managed keys and audited workflows.
  3. Customer-managed-key mode — Enterprise key ownership, rotation, and revocation through an approved KMS integration.

Do not implement all modes merely because they are listed. Create an ADR and threat model, select the supported modes, and make the user-facing promise match actual architecture.

Privileged support and impersonation

Routine “impersonate user” is unacceptable for private feedback. Where support access is necessary:

  • Require a case, reason, approver, tenant, scope, and expiry.
  • Prefer metadata-only diagnostics and tenant-admin screen sharing.
  • Display an unmistakable privileged-session banner.
  • Log start, actions, data classes accessed, and end.
  • Notify the tenant according to policy.
  • Block access to plaintext encrypted content unless a separately approved recovery process exists.
  • Never allow a global operator to silently become a tenant subject.

HR scope behavior

An HR designation should include:

  • Person or group
  • Org-unit scope
  • Include descendants flag
  • Allowed permissions
  • Effective start and end
  • Assignment source
  • Inheritance and conflicts
  • Last modified by
  • Audit history

The UI should preview the actual population and permissions before saving.

Required authorization tests

  • Cross-tenant object ID access is denied even when IDs are guessed.
  • A manager cannot access a non-report through route manipulation.
  • HR outside an org scope cannot see participation or aggregate results.
  • A platform operator cannot retrieve plaintext response or PDP content.
  • Revoked roles lose access immediately or within a documented token lifetime.
  • Archived users and leavers follow retention and access policies.
  • Export permissions are stricter than view permissions where needed.
  • Bulk endpoints enforce each row’s scope, not only the request’s tenant.
  • Support access expires and is immutable in audit history.