Organizations

Organizations allow users to create and manage teams, workspaces, or companies within your application. This feature provides a complete multi-tenant system with role-based access control, member management, and invitation workflows.

Overview

The organization system in Better Auth UI provides:

• Multi-organization Support: Users can create and belong to multiple organizations
• Role-Based Access Control: Built-in roles (owner, admin, member) plus custom roles
• Member Management: Invite, remove, and manage organization members
• Organization Switching: Seamlessly switch between organizations and personal accounts
• Permission System: Fine-grained permissions for different actions
• Invitation Workflow: Email-based invitation system with expiration

Enabling Organizations

To enable organizations, configure the organization prop in your AuthUIProvider:

<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic
        return uploadedUrl
      },
      size: 256,
      extension: "png"
    },
    customRoles: [
      { role: "developer", label: "Developer" },
      { role: "viewer", label: "Viewer" }
    ]
  }}
>
  {children}
</AuthUIProvider>

Key Components

OrganizationSwitcher

The main component for switching between organizations and personal accounts:

import { OrganizationSwitcher } from '@daveyplate/better-auth-ui'

<OrganizationSwitcher />

SettingsCards with Organization View

The settings component automatically shows organization options when enabled:

import { SettingsCards } from '@daveyplate/better-auth-ui'

// Shows organization settings when view="ORGANIZATION"
<SettingsCards view="ORGANIZATION" />

// Shows organization members when view="MEMBERS"
<SettingsCards view="MEMBERS" />

// Shows all organizations when view="ORGANIZATIONS"
<SettingsCards view="ORGANIZATIONS" />

Organization-Specific Components

• <OrganizationSettingsCards /> - Organization settings management
• <OrganizationMembersCard /> - Member management
• <OrganizationInvitationsCard /> - Pending invitations
• <OrganizationsCard /> - List all user's organizations
• <AcceptInvitationCard /> - Accept invitation flow

Built-in Roles

Organizations come with three built-in roles:

1. Owner

   • Full control over the organization
   • Can delete the organization
   • Can transfer ownership
   • Can manage all members and settings

2. Admin

   • Can manage organization settings
   • Can invite and remove members
   • Can update member roles (except owner)
   • Cannot delete the organization

3. Member

   • Basic access to the organization
   • Cannot manage settings or members
   • Can leave the organization

Custom Roles

You can define additional roles for your specific needs:

organization={{
  customRoles: [
    { role: "developer", label: "Developer" },
    { role: "viewer", label: "View Only" },
    { role: "billing", label: "Billing Administrator" }
  ]
}}

Organization Hooks

Access organization data programmatically:

import { useContext } from 'react'
import { AuthUIContext } from '@daveyplate/better-auth-ui'

function MyComponent() {
  const { hooks } = useContext(AuthUIContext)
  
  // Get active organization
  const { data: activeOrg } = hooks.useActiveOrganization()
  
  // List all organizations
  const { data: organizations } = hooks.useListOrganizations()
  
  // Check permissions
  const { data: hasPermission } = hooks.useHasPermission({
    permissions: {
      organization: ["update"],
      member: ["create", "delete"]
    }
  })
  
  return (
    <div>
      Current org: {activeOrg?.name}
    </div>
  )
}

Invitation Flow

1. Send Invitation: Admin/Owner sends invitation via email
2. Email Delivery: Recipient receives invitation email
3. Accept/Reject: User clicks link to accept or reject
4. Join Organization: User becomes a member with assigned role

Best Practices

1. Logo Configuration: Set up logo upload for better branding
2. Role Planning: Define custom roles based on your needs
3. Permission Checks: Always check permissions before sensitive actions
4. Invitation Expiry: Set reasonable expiration times
5. Member Limits: Consider implementing member limits for plans

Security Considerations

• Session Freshness: Some actions require fresh authentication
• Permission Validation: All actions are permission-checked server-side
• Invitation Security: Invitations include secure tokens
• Data Isolation: Organization data is properly isolated
• Audit Trail: Consider logging organization actions