🏢 organizations – Add organizations with members and invitations to your Rails SaaS

class User < ApplicationRecord
  has_organizations
end

current_user.create_organization!("Acme Corp")
current_user.send_organization_invite_to!("teammate@acme.com")

switch_to_organization!(@org)

current_user.is_organization_owner?     # => true
current_user.is_organization_admin?     # => true (owners inherit admin permissions)

gem "organizations"

class User < ApplicationRecord
  has_organizations
end

class User < ApplicationRecord
  has_organizations do
    max_organizations 5         # Limit how many orgs a user can own (nil = unlimited)
    create_personal_org true    # Auto-create org on signup (default: false)
    require_organization true   # Require users to have at least one org (default: false)
  end
end

# config/routes.rb
mount Organizations::Engine => '/'

org = current_user.create_organization!("Acme Corp")
# User automatically becomes the owner

current_user.send_organization_invite_to!("teammate@example.com")
# Sends invitation email: "John invited you to join Acme Corp"
# When accepted, user joins as :member (default role)

current_user.send_organization_invite_to!("teammate@example.com", organization: other_org)

# Quick role checks (in current organization)
current_user.is_organization_owner?   # => true/false
current_user.is_organization_admin?   # => true/false

# Permission checks
current_user.has_organization_permission_to?(:invite_members)
# "Does current user have organization permission to invite members?"

# Check role in a specific org
current_user.is_admin_of?(@org)
# "Is current user an admin of this org?"

current_user.is_member_of?(@org)
# "Is current user a member of this org?"

# User belongs to multiple organizations? No problem.
current_user.organizations        # => [acme, startup_co, personal]
switch_to_organization!(startup_co)  # Changes active org in session

class ProjectsController < ApplicationController
  before_action :require_organization!
  before_action :require_organization_admin!, only: [:create, :destroy]
end

# config/initializers/pricing_plans.rb
plan :hobby do
  limits :organization_members, to: 3
end

plan :growth do
  limits :organization_members, to: 25
end

# config/initializers/organizations.rb
Organizations.configure do |config|
  config.on_member_invited do |ctx|
    org = ctx.organization
    limit = org.current_plan.limit_for(:organization_members)

    if limit && org.member_count >= limit
      raise Organizations::InvitationError, "Member limit reached. Please upgrade your plan."
    end
  end
end

# Associations
user.organizations                      # All organizations user belongs to
user.memberships                        # All memberships (with roles)
user.owned_organizations                # Organizations where user is owner
user.pending_organization_invitations   # Invitations waiting to be accepted

# Current organization context
user.organization                       # Alias for current_organization (most common use)
user.current_organization               # Active org for this session
user.current_membership                 # Membership in active org
user.current_organization_role          # Role in current org => :admin

# Quick boolean checks
user.belongs_to_any_organization?           # "Does user belong to any org?"
user.has_pending_organization_invitations?  # "Does user have pending invites?"

# Permission checks (in current organization)
user.has_organization_permission_to?(:invite_members)   # => true/false
user.has_organization_role?(:admin)                     # => true/false

# Role shortcuts (in current organization)
user.is_organization_owner?             # Same as has_organization_role?(:owner)
user.is_organization_admin?             # Same as has_organization_role?(:admin)
user.is_organization_member?            # Same as has_organization_role?(:member)
user.is_organization_viewer?            # Same as has_organization_role?(:viewer)

# Role checks (explicit organization)
user.is_owner_of?(org)                  # "Is user an owner of this org?"
user.is_admin_of?(org)                  # "Is user an admin of this org?"
user.is_member_of?(org)                 # "Is user a member of this org?"
user.is_viewer_of?(org)                 # "Is user a viewer of this org?"
user.is_at_least?(:admin, in: org)      # "Is user at least an admin in this org?"
user.role_in(org)                       # => :admin

# Actions
user.create_organization!("Acme")            # Positional arg
user.create_organization!(name: "Acme")      # Keyword arg (both work)
user.leave_organization!(org)
user.leave_current_organization!             # Leave the active org
user.send_organization_invite_to!(email)                     # Invite to current org
user.send_organization_invite_to!(email, organization: org)  # Invite to specific org

# Associations
org.memberships                 # All memberships
org.members                     # All users (alias for org.users)
org.users                       # All users (through memberships)
org.invitations                 # All invitations (pending + accepted)
org.pending_invitations         # Invitations not yet accepted

# Queries
org.owner                       # User who owns this org
org.admins                      # Users with admin role or higher
org.has_member?(user)           # "Does org have this user as a member?"
org.has_any_members?            # "Does org have any members?"
org.member_count                # Number of members

# Class methods / Scopes
Organizations::Organization.with_member(user)  # Find all orgs where user is a member

# Actions
org.add_member!(user, role: :member)
org.remove_member!(user)
org.change_role_of!(user, to: :admin)
org.transfer_ownership_to!(other_user)

# Invitations (inviter must be a member with :invite_members permission)
org.send_invite_to!(email)                  # Auto-infers invited_by from Current.user
org.send_invite_to!(email, invited_by: user) # Explicit inviter

# Scopes
org.memberships.owners          # Memberships with owner role
org.memberships.admins          # Memberships with admin role
org.invitations.pending         # Not yet accepted
org.invitations.expired         # Past expiration date

membership.role                 # => "admin"
membership.organization         # The organization
membership.user                 # The user
membership.invited_by           # User who invited them (if any)

# Permission checks
membership.has_permission_to?(:invite_members)   # => true/false
membership.permissions                           # => [:view_members, :invite_members, ...]

# Role hierarchy checks
membership.is_at_least?(:member)    # => true (if member, admin, or owner)

# Role changes
membership.promote_to!(:admin)      # Change role to admin
membership.demote_to!(:member)      # Change role to member

invitation.email                # => "teammate@example.com"
invitation.organization         # The organization
invitation.role                 # Role they'll have when accepted
invitation.invited_by           # User who sent the invitation
invitation.from                 # Alias for invited_by
invitation.pending?             # => true (not yet accepted)
invitation.accepted?            # => true (has accepted_at)
invitation.expired?             # => true (past expires_at)

# Actions
invitation.accept!              # Accept (auto-infers Current.user)
invitation.accept!(user)        # Accept with explicit user
invitation.resend!              # Send invitation email again

class ApplicationController < ActionController::Base
  include Organizations::Controller
end

# Context helpers
current_organization            # Active organization (from session)
current_membership              # Current user's membership in active org
organization_signed_in?         # Is there an active organization?

# Authorization
require_organization!                               # Redirect if no active org
require_organization_role!(:admin)                  # Require at least admin role
require_organization_permission_to!(:invite_members) # Require specific permission

# Authorization shortcuts (for common roles)
require_organization_owner!     # Same as require_organization_role!(:owner)
require_organization_admin!     # Same as require_organization_role!(:admin)

# Switching
switch_to_organization!(org)       # Change active org in session

class SettingsController < ApplicationController
  before_action :require_organization!
  before_action :require_organization_admin!  # Shortcut for require_organization_role!(:admin)

  def billing
    require_organization_owner!  # Only owners can manage billing
  end
end

# config/initializers/organizations.rb
Organizations.configure do |config|
  config.on_unauthorized do |context|
    # context.user, context.organization, context.permission, context.required_role
    redirect_to root_path, alert: "You don't have permission to do that."
  end

  config.on_no_organization do |context|
    redirect_to new_organization_path, alert: "Please create or join an organization first."
  end
end

module ApplicationHelper
  include Organizations::ViewHelpers
end

<% if current_user.has_organization_permission_to?(:invite_members) %>
  <%= link_to "Invite teammate", new_invitation_path %>
<% end %>

<% if current_user.is_organization_admin? %>
  <%= link_to "Settings", organization_settings_path %>
<% end %>

<% data = organization_switcher_data %>

<div class="org-switcher">
  <button><%= data[:current][:name] %></button>
  <ul>
    <% data[:others].each do |org| %>
      <li>
        <%= link_to org[:name], data[:switch_path].call(org[:id]) %>
      </li>
    <% end %>
  </ul>
</div>

{
  current: { id: "...", name: "Acme Corp" },
  others: [
    { id: "...", name: "Personal" },
    { id: "...", name: "StartupCo" }
  ],
  switch_path: ->(org_id) { "/organizations/switch/#{org_id}" }
}

# Show pending invitation count in your navbar
<%= organization_invitation_badge(current_user) %>
# => <span class="badge">3</span> (if 3 pending invitations)
# => nil (if no pending invitations)

current_user.has_organization_permission_to?(:invite_members)
# "Can they invite people to this org?"

current_user.has_organization_permission_to?(:manage_billing)
# "Can they manage this org's billing?"

require_organization_permission_to!(:manage_settings)
# Gate org settings pages

# Pundit/CanCanCan territory (not what this gem does)
policy(@document).update?      # "Can they edit THIS specific document?"
authorize! :destroy, @project  # "Can they delete THIS specific project?"

# config/initializers/organizations.rb
Organizations.configure do |config|
  config.roles do
    role :viewer do
      can :view_organization
      can :view_members
    end

    role :member, inherits: :viewer do
      can :create_resources
      can :edit_own_resources
      can :delete_own_resources
    end

    role :admin, inherits: :member do
      can :invite_members
      can :remove_members
      can :edit_member_roles
      can :manage_settings
    end

    role :owner, inherits: :admin do
      can :manage_billing
      can :transfer_ownership
      can :delete_organization
    end
  end
end

role :admin, inherits: :member do
  can :invite_members
  can :remove_members
  can :manage_api_keys      # Your custom permission
  can :export_data          # Your custom permission
end

current_user.has_organization_permission_to?(:manage_api_keys)
require_organization_permission_to!(:export_data)

# Invite to your current organization (most common)
current_user.send_organization_invite_to!("teammate@example.com")

# Invite to a specific organization
current_user.send_organization_invite_to!("teammate@example.com", organization: other_org)

# All invitees join as :member by default. Admins can promote after joining.

org.send_invite_to!("teammate@example.com", invited_by: current_user)

# In your User model or registration controller
after_create :accept_pending_invitation

def accept_pending_invitation
  token = session.delete(:pending_invitation_token)
  return unless token

  invitation = Organizations::Invitation.find_by(token: token)
  invitation&.accept!(self, skip_email_validation: true)
end

# Customize the mailer in config
Organizations.configure do |config|
  config.invitation_mailer = "Organizations::InvitationMailer"  # Default
  # Or use your own: config.invitation_mailer = "CustomInvitationMailer"
end

Organizations.configure do |config|
  config.invitation_expiry = 7.days  # Default
  # config.invitation_expiry = 30.days
  # config.invitation_expiry = nil  # Never expire
end

invitation.expired?   # => true
invitation.resend!    # Generates new token, resets expiry, sends email

org.invitations.accepted  # Who was invited and when
invitation.accepted_at    # When they joined
invitation.invited_by     # Who sent the invitation

# In a controller
def switch
  org = current_user.organizations.find(params[:id])
  switch_to_organization!(org)
  redirect_to dashboard_path
end

# When always_create_personal_organization_for_each_user is enabled:
# 1. Organization created with name from config
# 2. User becomes owner of that organization
# 3. current_organization set to this new org

Organizations.configure do |config|
  # Enable auto-creation (disabled by default)
  config.always_create_personal_organization_for_each_user = true

  # Customize the name
  config.default_organization_name = ->(user) { "#{user.email.split('@').first}'s Workspace" }
  # Default: "Personal"
end

class User < ApplicationRecord
  has_organizations do
    create_personal_org true     # Auto-create org on signup
    require_organization true    # Require users to always have an org
  end
end

current_user.organization                    # => nil
current_user.current_organization            # => nil
current_user.belongs_to_any_organization?    # => false
current_user.is_organization_admin?          # => false (no org context)

# In controllers
current_organization                         # => nil
organization_signed_in?                      # => false
require_organization!                        # Redirects to on_no_organization handler

Organizations.configure do |config|
  config.on_no_organization do |context|
    redirect_to new_organization_path, notice: "Create or join an organization to continue."
  end
end

# config/initializers/organizations.rb
Organizations.configure do |config|
  # === Authentication ===
  # Method that returns the current user (default: :current_user)
  config.current_user_method = :current_user

  # Method that ensures user is authenticated (default: :authenticate_user!)
  config.authenticate_user_method = :authenticate_user!

  # === Auto-creation ===
  # Create personal organization on user signup (default: false)
  config.always_create_personal_organization_for_each_user = false

  # Name for auto-created organizations
  config.default_organization_name = ->(user) { "Personal" }

  # === Invitations ===
  # How long invitations are valid
  config.invitation_expiry = 7.days

  # Custom mailer for invitations
  config.invitation_mailer = "Organizations::InvitationMailer"

  # === Limits ===
  # Maximum organizations a user can own (nil = unlimited)
  config.max_organizations_per_user = nil

  # === Onboarding ===
  # Require users to belong to at least one organization
  # Set to true if users should always have an organization
  config.always_require_users_to_belong_to_one_organization = false  # Default

  # === Redirects ===
  # Where to redirect when user has no organization
  config.redirect_path_when_no_organization = "/organizations/new"

  # === Handlers ===
  # Called when authorization fails
  config.on_unauthorized do |context|
    redirect_to root_path, alert: "Not authorized"
  end

  # Called when no organization is set
  config.on_no_organization do |context|
    redirect_to config.redirect_path_when_no_organization
  end

  # === Roles & Permissions ===
  config.roles do
    # ... (see Roles and Permissions section)
  end

  # === Callbacks ===
  config.on_organization_created do |ctx|
    # ctx.organization, ctx.user (owner)
  end

  config.on_member_invited do |ctx|
    # ctx.organization, ctx.invitation, ctx.invited_by
  end

  config.on_member_joined do |ctx|
    # ctx.organization, ctx.membership, ctx.user
  end

  config.on_member_removed do |ctx|
    # ctx.organization, ctx.membership, ctx.user, ctx.removed_by
  end

  config.on_role_changed do |ctx|
    # ctx.organization, ctx.membership, ctx.old_role, ctx.new_role, ctx.changed_by
  end

  config.on_ownership_transferred do |ctx|
    # ctx.organization, ctx.old_owner, ctx.new_owner
  end
end

Organizations.configure do |config|
  config.current_user_method = :current_account
  config.authenticate_user_method = :require_login
end

class ApplicationController < ActionController::Base
  include Organizations::Controller
  include Organizations::ActsAsTenantIntegration
  # Automatically calls: set_current_tenant(current_organization)
end

# In your Organization model
class Organization < ApplicationRecord
  include PricingPlans::PlanOwner
end

# In config/initializers/pricing_plans.rb
plan :starter do
  limits :members, to: 5
end

plan :pro do
  limits :members, to: 50
end

# Organization owns API keys (api_keys gem)
class Organization < ApplicationRecord
  has_api_keys do
    max_keys 10
  end
end

# Organization has credits (usage_credits gem)
class Organization < ApplicationRecord
  has_credits
end

# Organization has pricing plan (pricing_plans gem)
class Organization < ApplicationRecord
  include PricingPlans::PlanOwner
end

current_organization.api_keys
current_organization.credits
current_organization.current_pricing_plan
current_organization.memberships  # From organizations gem

Organizations.configure do |config|
  config.on_organization_created do |ctx|
    SlackNotifier.notify("New org: #{ctx.organization.name}")
    Analytics.track(ctx.user, "organization_created")
  end

  config.on_member_joined do |ctx|
    WelcomeMailer.send_team_welcome(ctx.user, ctx.organization).deliver_later
    Analytics.track(ctx.user, "joined_organization", org: ctx.organization.name)
  end

  config.on_member_removed do |ctx|
    AuditLog.record(
      action: :member_removed,
      organization: ctx.organization,
      user: ctx.user,
      actor: ctx.removed_by
    )
  end
end

# test/test_helper.rb
require "organizations/test_helpers"

class ActiveSupport::TestCase
  include Organizations::TestHelpers
end

# Set organization context in tests
sign_in_as_organization_member(user, org, role: :admin)
set_current_organization(org)

# Or manually
sign_in user
switch_to_organization!(org)

assert user.is_member_of?(org)
assert user.is_owner_of?(org)
assert user.is_organization_admin?
assert user.has_organization_permission_to?(:invite_members)
assert user.belongs_to_any_organization?

# db/migrate/xxx_add_custom_fields_to_organizations.rb
class AddCustomFieldsToOrganizations < ActiveRecord::Migration[8.0]
  def change
    add_column :organizations, :support_email, :string
    add_column :organizations, :billing_address, :text
    add_column :organizations, :settings, :jsonb, default: {}
  end
end

# config/initializers/organization_extensions.rb
# Or: app/models/concerns/organization_extensions.rb (then include in initializer)

Organizations::Organization.class_eval do
  # Add your own associations
  has_many :projects
  has_many :documents

  # Add your own validations
  validates :support_email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }

  # Add your own methods
  def active_projects
    projects.where(archived: false)
  end
end

# app/models/organization.rb
class Organization < Organizations::Organization
  has_many :projects
  has_many :documents

  validates :support_email, presence: true
end

# Listing members — GOOD
org.memberships.includes(:user).each do |membership|
  membership.user.name  # No N+1
end

# Listing members — BAD (N+1 on user)
org.memberships.each do |membership|
  membership.user.name  # Queries DB for each user
end

# Listing invitations — GOOD
org.invitations.includes(:invited_by).each do |invitation|
  invitation.invited_by.name  # No N+1
end

# This does NOT query the DB
user.has_organization_permission_to?(:invite_members)

# Safe to call in loops
org.memberships.includes(:user).each do |m|
  m.has_permission_to?(:invite_members)  # No DB query, just hash lookup
end

# If memberships are already loaded, this won't query again
user.organizations.includes(:memberships).each do |org|
  user.is_admin_of?(org)  # Reuses loaded membership
end

# But if you call it in isolation, it queries the DB
user.is_admin_of?(some_org)  # Single query to find membership

# Internally, it:
# 1. Selects only id, name (not full objects)
# 2. Memoizes within the request
# 3. Returns a lightweight hash, not ActiveRecord objects

organization_switcher_data
# => { current: { id: "...", name: "Acme" }, others: [...] }

# In a migration
add_column :organizations, :memberships_count, :integer, default: 0, null: false

# Reset existing counts
Organization.find_each do |org|
  Organization.reset_counters(org.id, :memberships)
end

org.member_count
# Uses memberships_count column if it exists
# Falls back to COUNT(*) query otherwise

user.belongs_to_any_organization?     # SELECT 1 FROM memberships WHERE ... LIMIT 1
user.has_pending_organization_invitations?  # SELECT 1 FROM organization_invitations WHERE ... LIMIT 1
org.has_any_members?                  # SELECT 1 FROM memberships WHERE ... LIMIT 1

org.admins
# SELECT users.* FROM users
# INNER JOIN memberships ON memberships.user_id = users.id
# WHERE memberships.organization_id = ? AND memberships.role IN ('admin', 'owner')

user.owned_organizations
# SELECT organizations.* FROM organizations
# INNER JOIN memberships ON memberships.organization_id = organizations.id
# WHERE memberships.user_id = ? AND memberships.role = 'owner'

# In your controller, these all return the same cached object
current_organization  # Queries DB (first call)
current_organization  # Returns cached (subsequent calls)
current_organization  # Returns cached

# Future API
org.bulk_invite!(emails, skip_callbacks: true)
# Fires on_bulk_invited once instead of on_member_invited N times

# Two users clicking "Accept" on same invitation simultaneously
invitation.accept!

# Internally:
# 1. Lock invitation row
# 2. Check accepted_at is nil
# 3. Create membership
# 4. Set accepted_at
# 5. Release lock
# Second request sees accepted_at is set, returns existing membership

org.transfer_ownership_to!(new_owner)

# Internally:
# 1. Lock organization row
# 2. Lock old owner's membership
# 3. Lock new owner's membership
# 4. Verify new owner is a member
# 5. Demote old owner to admin
# 6. Promote new owner to owner
# 7. Release locks

user.leave_organization!(org)

# Internally:
# 1. Lock organization row
# 2. Count remaining owners/admins
# 3. If last owner, raise CannotLeaveAsLastOwner
# 4. If allowed, destroy membership
# 5. Release lock

membership.promote_to!(:admin)

# Internally:
# 1. Lock membership row
# 2. Update role
# 3. Release lock

# Organization creation (atomic)
user.create_organization!("Acme")
# Transaction: create org → create owner membership → set as current org

# Invitation acceptance (atomic)
invitation.accept!
# Transaction: lock invitation → create membership → update accepted_at

# Ownership transfer (atomic)
org.transfer_ownership_to!(user)
# Transaction: lock rows → demote old owner → promote new owner

# Inviting an already-invited email
current_user.send_organization_invite_to!("already@invited.com")
# => Returns existing pending invitation (doesn't raise)

# Accepting an already-accepted invitation
invitation.accept!
# => Returns existing membership (doesn't raise)

# Adding an existing member
org.add_member!(existing_user)
# => Returns existing membership (doesn't raise)

# User's session points to org_id = 123
# Admin removes user from org 123

# On user's next request:
current_organization
# 1. Finds org 123
# 2. Verifies user has membership in org 123
# 3. Membership doesn't exist → clears session, returns nil
# 4. require_organization! redirects to on_no_organization handler