Better Auth UI

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:

providers.tsx

<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 "@/components/organization/organization-switcher";

<OrganizationSwitcher />;

SettingsCards with Organization View

The settings component automatically shows organization options when enabled:

import { AccountView } from 'better-auth-ui'

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

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

// Shows all organizations when view="ORGANIZATIONS"
<AccountView 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:

Owner
- Full control over the organization
- Can delete the organization
- Can transfer ownership
- Can manage all members and settings
Admin
- Can manage organization settings
- Can invite and remove members
- Can update member roles (except owner)
- Cannot delete the organization
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 "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

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

Best Practices

Logo Configuration: Set up logo upload for better branding
Role Planning: Define custom roles based on your needs
Permission Checks: Always check permissions before sensitive actions
Invitation Expiry: Set reasonable expiration times
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

Organizations