Organization

The OrganizationPlugin provides multi-tenancy support with organizations, membership management, invitation workflows, and role-based access control (RBAC).

Setup

These examples assume you've already defined AppAuthSchema. If you want a complete setup from entity definitions through Axum mounting, start with the Axum integration guide.

use better_auth::plugins::OrganizationPlugin;

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(OrganizationPlugin::new())
    .build()
    .await?;

Configuration

use better_auth::plugins::organization::OrganizationConfig;

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(
        OrganizationPlugin::new()
            .allow_user_to_create_organization(true)
            .organization_limit(5)
            .membership_limit(50)
            .creator_role("owner")
            .invitation_expires_in(172800) // 48 hours
            .invitation_limit(100)
    )
    .build()
    .await?;

Configure invitation delivery with OrganizationPlugin::custom_send_invitation_email(Arc<dyn SendInvitationEmail>). Implement SendInvitationEmail::send using the invitation, organization, member, and inviter in InvitationEmail. The plugin logs delivery failures and still returns the stored invitation, matching upstream behavior.

Inviting an email with a pending invitation returns USER_IS_ALREADY_INVITED_TO_THIS_ORGANIZATION. Send resend: true to renew that invitation and send the email again. Resending preserves the invitation ID, role, and original inviter.

RBAC (Role-Based Access Control)

Default Roles

The apikey resource governs organization-owned keys from the API Key plugin. Matching upstream, no default role is granted any action on it; the creator role (creator_role, "owner" by default) is allowed everything implicitly, and other roles need an explicit grant through a custom role.

Custom Roles

Extend the default roles with custom permissions:

use better_auth::plugins::organization::config::{OrganizationConfig, RolePermissions};
use std::collections::HashMap;

let mut roles = HashMap::new();
roles.insert("editor".to_string(), RolePermissions {
    organization: vec!["read".to_string()],
    member: vec!["read".to_string()],
    invitation: vec![],
    api_key: vec!["read".to_string(), "create".to_string()],
});

let config = OrganizationConfig {
    roles,
    ..Default::default()
};

let auth = BetterAuth::<AppAuthSchema>::new(auth_config)
    .store(store)
    .plugin(OrganizationPlugin::with_config(config))
    .build()
    .await?;

Resources and Actions

Resources: organization, member, invitation, apikey

Actions: create, read, update, delete, cancel

API Endpoints

For full request/response details, see the OpenAPI Reference.

Organization CRUD

Member Management

Invitations

Permission Check

Errors