Organizations (Multi-tenant)

Organizations enable multi-tenant functionality where users can create workspaces, invite team members, and collaborate with role-based permissions.

How to Activate

1

Enable organization mode

bash

# Set billing mode to organization-based
NEXT_PUBLIC_BILLING_MODE="organization"

# Enable organization pages
NEXT_PUBLIC_ENABLED_PAGES="organization,invitation,account,settings,subscription"

# Email service required for invitations
RESEND_API_KEY="re_your_resend_api_key"
EMAIL_FROM="noreply@yourdomain.com"

2

That's it!

Organization features automatically appear in user account at /[locale]/account/organizations.

How Organizations Work

Multi-tenant Concept

Organization structure:

• Owner - Full control, billing, can delete organization
• Admin - Manage members, settings, but cannot delete
• Member - Basic access, use organization features

User experience:

• Users switch between organizations
• Each organization has its own data and settings
• Invitations allow users to join multiple organizations

Organization Selection Interface:

Organization Management

Creating Organizations

Organization Settings

Location: /[locale]/account/organizations/[id]/edit

Available settings:

• Basic info - Name, description, avatar
• Member management - Invite, remove, change roles
• Billing settings - Subscription management (if enabled)
• Danger zone - Delete organization (owner only)

Organization Members Management:

Member Roles Management:

Member Management

Inviting Members

1

Go to organization settings

Organization owner/admin visits /[locale]/account/organizations/[id] and clicks "Invite Members".

2

Send invitation

• Enter email address of person to invite
• Select role (Admin or Member)
• Add optional invitation message

3

Invitation email sent

Invitee receives email with invitation link and organization details.

4

Accept invitation

Invitee clicks link, goes to /[locale]/account/invitations/[id], and can accept or decline.

Member Roles & Permissions

Invitation Management

Invitation limits: 10 pending invitations per organization (configurable)

Invitation features:

• Pending invitations - Track sent invitations
• Expiration - Invitations expire after set time
• Resend - Can resend invitations if needed
• Cancel - Can cancel pending invitations

User invitation page: /[locale]/account/invitations

• View all pending invitations
• Accept or decline each invitation
• See organization details before joining

Detailed Members Management Interface:

Billing Mode Impact

Organization Billing vs User Billing

NEXT_PUBLIC_BILLING_MODE="organization"

NEXT_PUBLIC_BILLING_MODE="user"

Subscription Management

With organization billing:

• Subscriptions are attached to organizations
• Only owners can manage billing
• Members benefit from organization subscription
• Usage/limits are per-organization

Subscription pages:

• /[locale]/account/billing/subscription - Current organization's subscription
• Organization switching affects which subscription is shown

Better Auth Configuration

The organization system uses Better Auth's organization plugin:

// In src/lib/better-auth/auth.ts
organization({
  invitationLimit: 10,              // Max pending invitations
  membershipLimit: 10,              // Max members per organization
  allowUserToCreateOrganization: false,  // Only admins can create

  async sendInvitationEmail(data) {
    const inviteLink = `${env.NEXT_PUBLIC_APP_URL}/invitations/${data.id}`

    // Send via notification service
    await createTypedNotificationService({
      userId: invitedUser.id,
      type: NotificationTypeConst.organization_invitation,
      metadata: {
        organizationId: data.organization.id,
        organizationName: data.organization.name,
        invitedBy: data.inviter.user.name,
        role: data.role,
      }
    })
  }
})

Key configuration:

• Invitation limit: 10 pending invitations per organization
• Member limit: 10 members per organization
• User creation: Disabled by default (admin-only)
• Email notifications: Automatic via notification service

Organization Pages Structure

src/app/[locale]/(app)/account/
├── organizations/
│   ├── page.tsx                    # List all user's organizations
│   └── [id]/
│       ├── page.tsx                # Organization details & members
│       └── edit/
│           └── page.tsx            # Organization settings
└── invitations/
    ├── page.tsx                    # List pending invitations
    └── [id]/
        └── page.tsx                # Accept/decline specific invitation

User Experience Flows

Creating and Managing Organization

Switching Organizations

User can:

• View all organizations they belong to
• Switch active organization context
• See different data/settings per organization
• Have different roles in different organizations

Common Issues & Solutions

Security & Permissions

Permission validation:

• All organization operations check user roles
• API endpoints validate organization membership
• UI shows/hides features based on permissions
• Database queries filter by organization access

Administration Interface:

Testing Checklist