Skip to main content

Organizations

Organizations provide a hierarchical structure within a tenant for grouping users and managing access control.

Organization Model​

interface Organization {
  id: string;           // UUID
  name: string;         // Display name
  slug: string;         // URL-friendly identifier
  tenantId: string;     // Parent tenant
  parentId: string | null; // Parent organization (null = root)
  status: OrganizationStatus;
  createdAt: Date;
  updatedAt: Date;
}

enum OrganizationStatus {
  ACTIVE = 'ACTIVE',
  INACTIVE = 'INACTIVE',
}

Hierarchical Structure​

Organizations can be nested to represent company structure:

Acme Corporation (Tenant)
├── Engineering (Organization)
│   ├── Frontend Team (Organization)
│   ├── Backend Team (Organization)
│   └── DevOps Team (Organization)
├── Sales (Organization)
│   ├── North America (Organization)
│   └── Europe (Organization)
└── Human Resources (Organization)

Use Cases​

1. Department Structure​

Model your company's departments and teams.

2. Geographic Regions​

Organize by location (headquarters, regional offices).

3. Project Teams​

Create temporary organizations for projects.

4. Access Control​

Scope roles and permissions to specific organizations.

Endpoints​

MethodEndpointDescription
POST/organizationsCreate organization
GET/organizationsList organizations
GET/organizations/:idGet organization
PATCH/organizations/:idUpdate organization
DELETE/organizations/:idDelete organization
GET/organizations/:id/treeGet organization hierarchy
GET/organizations/:id/childrenGet direct children

Organization Isolation​

Organizations within a tenant are isolated from each other when using organization-scoped roles:

User with ORG_ADMIN role in "Engineering":
  ✓ Can manage Engineering users
  ✓ Can manage Frontend Team users (child org)
  ✓ Can manage Backend Team users (child org)
  ✗ Cannot manage Sales users
  ✗ Cannot manage HR users

Hierarchy Depth​

By default, organizations can be nested up to 5 levels deep:

Level 0: Root Organization
  Level 1: Department
    Level 2: Division
      Level 3: Team
        Level 4: Sub-team

This limit is configurable per tenant in settings.

Key Concepts​

Root Organizations​

Organizations without a parentId are root organizations. A tenant can have multiple root organizations.

Cascading Operations​

Some operations cascade to child organizations:

  • Deactivating a parent org deactivates all children
  • Deleting a parent org requires children to be deleted first or reassigned

User Membership​

Users can belong to multiple organizations through memberships, with different roles in each.