Auth & Permissions

The auth module handles authentication, organization membership, and access control. It consists of three interconnected subsystems:

Subsystem	Purpose
ABAC Authorization	Attribute-Based Access Control for all API endpoints
Permission-Aware UI	Conditional rendering based on user permissions
Invitations	Invite new users into an organization

Key Concepts

Organization — the top-level tenant. Every user belongs to exactly one organization.

Member — the link between a user and an organization. A member can be an owner (is_owner: true) or a regular member.

Role — a named set of permissions assigned to a member. A member can have multiple roles.

Permission — a granular capability over a resource (e.g., Agent:Collection:List, Call:Instance:Update). Permissions serialize as colon-separated strings: Resource:Level:Variant.

Super-admin — a platform-level flag (user.is_super_admin) that bypasses all checks, including org-scoping.

Access Levels (Hierarchy)

Super-admin → bypasses everything (cross-org access)
  ↓
Org owner   → full access within their org
  ↓
Member      → only what their roles grant
  ↓
(no role)   → 403 on all permission-gated endpoints

Database Schema

-- Roles defined per org
CREATE TABLE role (
    id              UUID PRIMARY KEY,
    organization_id UUID NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
    name            TEXT NOT NULL,
    description     TEXT,
    permissions     JSONB NOT NULL DEFAULT '[]'
);

-- Members can hold multiple roles
CREATE TABLE member_role (
    id        UUID PRIMARY KEY,
    member_id UUID NOT NULL REFERENCES member(id) ON DELETE CASCADE,
    role_id   UUID NOT NULL REFERENCES role(id) ON DELETE CASCADE,
    UNIQUE (member_id, role_id)
);

-- Super-admin flag on the user table
ALTER TABLE "user" ADD COLUMN is_super_admin BOOLEAN NOT NULL DEFAULT false;

-- Owner flag on the member table
ALTER TABLE member ADD COLUMN is_owner BOOLEAN NOT NULL DEFAULT false;

Related Modules

• Settings — organization profile and user account management
• Call — Call:Instance:Update gates the “Rerun Analysis” action
• Contact — ContactNote supports ownership-based permissions (ViewOwn, UpdateOwn, DeleteOwn)