Teams & Organizations

Overview

Codapult provides built-in multi-tenancy through organizations. Users can create teams, invite members, assign roles, and manage settings — all with fine-grained role-based access control (RBAC).

Roles & Hierarchy

Every organization member has one of four roles, ordered from most to least privileged:

| Role | Level | Capabilities | | ---------- | ----- | ------------------------------------------------------ | | Owner | 4 | Full control — delete org, manage billing, all actions | | Admin | 3 | Manage members, settings, billing, resources | | Member | 2 | Create and edit resources, view billing | | Viewer | 1 | Read-only access to org resources and settings |

Global admins (user.role === 'admin') bypass all organization-level permission checks.

Permissions

Permissions are defined in src/lib/permissions.ts as a map of action to allowed roles:

const permissions = {
  'org:update': ['owner', 'admin'],
  'org:delete': ['owner'],
  'member:invite': ['owner', 'admin'],
  'member:remove': ['owner', 'admin'],
  'member:update-role': ['owner', 'admin'],
  'member:list': ['owner', 'admin', 'member', 'viewer'],
  'billing:manage': ['owner', 'admin'],
  'billing:view': ['owner', 'admin', 'member'],
  'resource:create': ['owner', 'admin', 'member'],
  'resource:read': ['owner', 'admin', 'member', 'viewer'],
  'resource:update': ['owner', 'admin', 'member'],
  'resource:delete': ['owner', 'admin'],
  'settings:manage': ['owner', 'admin'],
  'invitation:create': ['owner', 'admin'],
  'invitation:revoke': ['owner', 'admin'],
} satisfies Record<string, readonly OrgRole[]>;

Use the helper functions to check permissions in your code:

import { hasPermission, isRoleAtLeast, canModifyRole } from '@/lib/permissions';

hasPermission('member', 'resource:create'); // true
hasPermission('viewer', 'resource:create'); // false
isRoleAtLeast('admin', 'member'); // true
canModifyRole('admin', 'owner'); // false (must be strictly higher)

Guards

Server actions and API routes use guards from src/lib/guards.ts to enforce access control:

| Guard | Checks | | ------------------------ | -------------------------------------------------- | | requireAuth() | User is logged in — throws if not | | requireOrgMembership() | User is a member of the organization | | requireOrgAdmin() | User is an owner or admin of the organization | | requireOrgPermission() | User has a specific permission in the organization |

Usage in Server Actions

'use server';

import { requireOrgPermission } from '@/lib/guards';

export async function updateOrgSettings(orgId: string, data: unknown) {
  const { session, role } = await requireOrgPermission(orgId, 'settings:manage');

  // Only owners and admins reach this point
  // ... update settings ...
}

Usage in API Routes

import { requireOrgMembership } from '@/lib/guards';

export async function GET(req: Request) {
  const orgId = req.headers.get('x-org-id');
  if (!orgId) return NextResponse.json({ error: 'Missing org' }, { status: 400 });

  const { session } = await requireOrgMembership(orgId);
  // ... return org data ...
}

Invitations

Organization owners and admins can invite new members by email:

1. Admin sends an invitation from Dashboard → Team → Invite Member
2. An email with a unique token is sent to the invitee
3. The invitee clicks the link and lands on /invite/[token]
4. After accepting, they become a member with the assigned role

Invitations have an expiration date. Expired invitations cannot be accepted — the admin must resend.

Invitation Statuses

| Status | Description | | ---------- | ------------------------------- | | pending | Sent, awaiting acceptance | | accepted | Invitee joined the organization | | expired | Token expired before acceptance |

Database Tables

Three tables power the teams module:

organization

| Column | Type | Description | | ------------ | --------- | ---------------------------- | | id | text (PK) | Unique ID (nanoid) | | name | text | Display name | | slug | text | URL-safe unique identifier | | image | text | Avatar URL (optional) | | branding | text | JSON-encoded theme overrides | | created_at | timestamp | Creation date | | updated_at | timestamp | Last modified date |

organization_member

| Column | Type | Description | | ----------------- | --------- | ------------------------------------ | | id | text (PK) | Unique ID | | organization_id | text (FK) | References organization.id | | user_id | text (FK) | References user.id | | role | text | owner, admin, member, viewer | | created_at | timestamp | Joined date |

organization_invitation

| Column | Type | Description | | ----------------- | --------- | -------------------------------- | | id | text (PK) | Unique ID | | organization_id | text (FK) | References organization.id | | email | text | Invitee email address | | role | text | Assigned role on acceptance | | token | text | Unique invitation token | | status | text | pending, accepted, expired | | invited_by | text (FK) | References user.id | | expires_at | timestamp | Expiration date | | created_at | timestamp | Invitation sent date |

Server Actions

All team mutations are in src/lib/actions/organizations.ts:

| Action | Description | Required Permission | | ------------------- | ------------------------------ | -------------------- | | Create organization | Creates a new team | Authenticated user | | Update organization | Updates name, avatar, branding | org:update | | Delete organization | Permanently deletes the team | org:delete | | Invite member | Sends an email invitation | member:invite | | Change member role | Promotes or demotes a member | member:update-role | | Remove member | Removes a member from the team | member:remove |

UI Components

• TeamSwitcher — dropdown in the dashboard sidebar for switching between organizations
• Team settings page — manage name, avatar, and billing at Dashboard → Settings → Team
• Members list — view, invite, and manage members at Dashboard → Team

Module Removal

The teams module is independently removable. See the Modules documentation for step-by-step removal instructions.

Next Steps

• Database — schema conventions and query patterns
• Payments & Billing — subscription management tied to organizations
• Authentication — user accounts and sign-in methods