Organisations

Organisations are the top-level containers in Quox, grouping users, teams, and resources together with proper access control and scope management.

What are Organisations?

Organisations are the top-level containers for everything in Quox. Think of an organisation as a company, department, or project team that groups related users and resources together.

In simple terms: An organisation is like a folder that contains your teams, assistants, workflows, and inboxes. Everyone in the organisation can share and collaborate on these resources.

Organisation hierarchy

Quox uses a 4-level hierarchy to organise your workspace:

Organisation (depth=0)
└── Division (depth=1)
    └── Department (depth=2)
        └── Team (depth=3)

Scopes

Every level in the hierarchy has an associated scope. Scopes determine:

• What resources are visible at that level
• Who can access those resources
• What permissions apply

Scopes inherit permissions from their parent. If you have access to an organisation, you have access to all divisions, departments, and teams within it (based on your role).

Managing organisations

Creating an organisation

1. Navigate to Organisations from the sidebar
2. Click Create Organisation
3. Enter a name and optional description
4. You become the owner with full administrative rights

Organisation roles

Inviting members

1. Go to your organisation's management page
2. Click Invite Member
3. Enter the email address and select a role
4. The user receives an invitation email with a link to join

API reference

Endpoints

Create organisation

curl -X POST /api/orgs \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "My Organization", "slug": "my-org"}'

Invite member

curl -X POST /api/orgs/<orgId>/members \
  -H "Authorization: Bearer <token>" \
  -d '{"email": "[email protected]", "role": "builder"}'

Frontend implementation

Components

Context

The WorkspaceContext manages organisation state:

import { useWorkspace } from '../../contexts/WorkspaceContext'

function MyComponent() {
  const { currentOrg, myOrgs, isOrgAdmin } = useWorkspace()

  // currentOrg - The active organization
  // myOrgs - List of organizations user belongs to
  // isOrgAdmin - Whether user is admin of current org
}

Database schema

Tables

-- Organizations
CREATE TABLE orgs (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  logo_url TEXT,
  plan TEXT DEFAULT 'free',
  mfa_policy TEXT DEFAULT 'optional',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Organization memberships
CREATE TABLE org_memberships (
  id TEXT PRIMARY KEY,
  org_id TEXT NOT NULL REFERENCES orgs(id),
  user_id TEXT NOT NULL REFERENCES users(id),
  role TEXT NOT NULL DEFAULT 'viewer',
  status TEXT DEFAULT 'active',
  joined_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Scopes for permission inheritance
CREATE TABLE scopes (
  id TEXT PRIMARY KEY,
  org_id TEXT NOT NULL REFERENCES orgs(id),
  type TEXT NOT NULL, -- 'org', 'division', 'department', 'team'
  entity_id TEXT NOT NULL,
  parent_scope_id TEXT REFERENCES scopes(id),
  depth INTEGER NOT NULL DEFAULT 0
);

Last updated: 2026-01-22