Multi-Tenant Authentication

Overview

The do.dev application supports multi-tenant authentication through organizations and teams. Users can belong to multiple organizations with different roles and permissions within each organization.

Key Features

1. Organization-Based Access

• Users can be members of multiple organizations
• Each organization has its own set of members, roles, and permissions
• Organization isolation ensures data privacy between tenants

2. Database Structure

• users table for individual user profiles
• organizations table for tenant isolation
• organizationMembers table for user-organization relationships with roles
• Indexes ensure proper access control and performance

3. Authentication Flow

Sign Up

1. User provides email/password on the do.dev sign-up page
2. System creates user account with default "waitlist" role
3. Admin approval required for access to platform features
4. User can be invited to organizations after approval

Sign In

1. User provides credentials through Clerk authentication
2. System verifies user account and role status
3. User gains access based on their role and organization memberships
4. Dashboard shows organizations the user belongs to

OAuth (GitHub/Google)

1. User authenticates with OAuth provider
2. Clerk handles OAuth flow and user creation
3. User sync creates account in Convex with default "waitlist" role
4. Admin approval process same as email/password signup

Implementation Details

Frontend Organization Management

// hooks/useOrganizations.ts
export function useOrganizations() {
  // Get user's organizations and current organization
  // Handle organization switching
  // Manage organization permissions
}

// components/organization-switcher.tsx
export function OrganizationSwitcher() {
  // UI component for switching between organizations
  // Shows user's role in each organization
}

Backend Queries

// Get user's organizations
getUserOrganizations({ userId: "usr_xxxxx" })

// Check user role in organization
getUserRoleInOrganization({ userId: "usr_xxxxx", organizationId: "org_xxxxx" })

// Get organization members
getOrganizationMembers({ organizationId: "org_xxxxx" })

Organization Management

Creating Organizations

// Create new organization
await convex.mutation(api.organizations.create, {
  name: "My Company",
  slug: "my-company",
  ownerId: currentUser.id
});

Inviting Members

// Invite user to organization
await convex.mutation(api.organizations.inviteMember, {
  organizationId: "org_xxxxx",
  email: "user@example.com",
  role: "member"
});

Benefits

1. Multi-Tenant Support: Complete isolation between organizations
2. Flexible Roles: Different roles per organization (owner, admin, member)
3. Scalable Architecture: Supports enterprise customers with teams
4. Data Isolation: Organization data is completely segregated

Considerations

1. Users can belong to multiple organizations
2. Role-based access control per organization
3. Organization switching requires permission checks
4. Admin approval required for new user accounts