User Invitations, Roles & Permissions Guide

This comprehensive guide covers how to invite team members, manage roles, assign permissions, and understand how it affects billing.

Overview

SWELLEnterprise uses a role-based access control (RBAC) system where:

• Users belong to Tenants (organizations)
• Users have roles within each tenant (owner, admin, member, guest)
• Roles have permissions that control what users can do
• User limits are enforced based on your subscription plan

User Invitation System

How to Invite Users

Location: Settings → Team

1. Click "Invite User" button (top right of Team page)
2. Fill in invitation details:

• Email Address (required): The email of the person you want to invite
• Name (optional): Their name (will be asked during acceptance if not provided)
• Role (required): Choose from:
• • Member: Standard access with basic permissions
  • Admin: Full access to manage users and settings
  • Guest: Read-only access

3. Click "Send Invitation"
4. The invited user receives an email with an invitation link
5. They click the link, set up their account (if new), and join your team

Invitation Process Flow

For New Users (Don't have an account):

1. User receives invitation email
2. Clicks "Accept Invitation" link
3. Lands on acceptance page showing:

• Company name they're being invited to
• Inviter's name
• Role they'll have
• Expiration date

4. Fills in:

• Name
• Password
• Password confirmation

5. Clicks "Accept Invitation"
6. Account is created
7. User is automatically added to the tenant
8. User is logged in and redirected to dashboard
9. Email is automatically verified (invitation is email verification)

For Existing Users (Already have an account):

1. User receives invitation email
2. Clicks "Accept Invitation" link
3. If already logged in, they're added immediately
4. If not logged in:

• Logged in automatically
• Added to the tenant
• Redirected to dashboard

5. Can now switch to this tenant from their tenant switcher

Invitation Management

View Pending Invitations:

• Pending invitations appear at the top of the Team page
• Shows email, inviter, role, and expiration time
• Can resend or cancel invitations

Resend Invitation:

• Click "Resend" on a pending invitation
• New email is sent with the same link

Cancel Invitation:

• Click "Cancel" on a pending invitation
• Invitation is deleted and cannot be used

Invitation Expiration:

• Invitations expire after 7 days
• Expired invitations cannot be accepted
• Must create a new invitation if expired

User Roles

Role Types

Roles are assigned per-tenant (users can have different roles in different tenants).

Owner

• Created by: Assigned to the first user who creates a tenant
• Permissions: Full access to everything in the tenant
• Can:
• Manage all users and invitations
• Change tenant settings
• Manage billing and subscriptions
• Access all modules
• View and edit all records
• Delete the tenant (if enabled)
• Cannot: Be removed or changed by other users

Admin

• Permissions: Nearly full access, similar to owner
• Can:
• Invite and manage users
• Edit tenant settings
• Access all modules
• View and edit all records
• Manage some settings
• Typically Cannot: Manage billing (unless explicitly permitted)

Member

• Permissions: Standard user access
• Can:
• Access modules based on permissions
• Create and edit their own records
• View shared records
• Edit records they have access to
• Cannot:
• Invite users
• Change tenant settings
• Manage billing
• Delete records owned by others (unless permitted)

Guest

• Permissions: Read-only access
• Can:
• View records (based on permissions)
• Access limited modules
• Cannot:
• Create records
• Edit records
• Delete records
• Invite users
• Change settings

Role Assignment

During Invitation:

• Select role when inviting: Member, Admin, or Guest
• Role is assigned when invitation is accepted

After Invitation:

• Go to Settings → Team
• Click "Edit" on a team member
• Change their role
• Save changes
• Changes take effect immediately

Note: You cannot change the "Owner" role of the tenant creator.

Permissions System

How Permissions Work

SWELLEnterprise uses Spatie Laravel Permission with tenant scoping:

1. Permissions are defined per module (e.g., crm.view, crm.create, projects.edit)
2. Roles are assigned to users within a tenant context
3. Roles have permissions attached to them
4. Permissions are checked when users try to perform actions

Permission Structure

Permissions follow a pattern: {module}.{action}

Examples:

• crm.view - View CRM records
• crm.create - Create CRM records
• crm.edit - Edit CRM records
• crm.delete - Delete CRM records
• projects.view - View projects
• finance.approve - Approve financial transactions
• tenant.settings.edit - Edit tenant settings
• tenant.users.manage - Manage team members

Permission Checks in Code

Middleware:

// Protect routes with permission middleware
Route::middleware(['auth', 'permission:crm.create'])->group(function () {
    // Routes requiring crm.create permission
});

In Components:

// Check permissions in Livewire components
if (!auth()->user()->hasTenantPermission('crm.create')) {
    abort(403, 'You do not have permission to create CRM records.');
}

In Views:

@can('crm.create')
    <button>Create Contact</button>
@endcan

Default Permissions by Role

Owner:

• All permissions for all modules
• Tenant management permissions

Admin:

• Most permissions (may exclude billing)
• Can manage users and some settings

Member:

• View permissions for active modules
• Create/edit permissions for their own records
• Limited to modules enabled for tenant

Guest:

• View permissions only
• No create/edit/delete permissions

Customizing Permissions

Via Role Manager:

1. Go to Settings → Roles & Permissions (if available)
2. Select a role
3. Enable/disable specific permissions
4. Save changes

Via Code:

// Assign permission to a role
$role = Role::findByName('member');
$role->givePermissionTo('crm.create');

// Remove permission from role
$role->revokePermissionTo('crm.create');

// Assign permission directly to user (in tenant context)
$user->assignTenantRole('member');
$user->givePermissionTo('crm.create'); // Tenant-scoped

Team Management (CRUD Operations)

Creating/Inviting Users

Process:

1. Settings → Team → "Invite User"
2. Enter email, name (optional), role
3. Send invitation
4. User receives email and accepts

What Happens:

• Invitation record created in database
• Email sent via UserInvitationNotification
• User slot is checked (but not consumed until acceptance)
• If at limit, invitation cannot be sent

Reading/Viewing Users

Team List:

• Settings → Team tab
• Shows all team members with:
• Name and email
• Role
• Join date
• Actions (Edit/Remove buttons)

Search:

• Use search box to filter by name or email

Pagination:

• List is paginated (10 per page)

Updating Users

Edit User:

1. Click "Edit" on team member
2. Modal opens with:

• Name (editable)
• Email (read-only)
• Role (dropdown)

3. Make changes
4. Click "Save Changes"

What Updates:

• User's name in the system
• Role in tenant_user pivot table
• Permissions based on new role (if role manager assigns permissions to roles)

Deleting/Removing Users

Remove User:

1. Click "Remove" on team member
2. Confirm removal
3. User is removed from tenant

What Happens:

• User is detached from tenant (tenant_user pivot deleted)
• User slot is freed up
• User can no longer access this tenant
• If user's current_tenant_id was this tenant, it's cleared
• User's data remains (soft delete if enabled)

Note: You cannot remove yourself (the current logged-in user).

Billing Impact

User Limits by Plan

User limits are enforced based on your subscription plan:

During Trial:

• Business plan limits apply (25 users)
• No billing until trial ends

Adding Users - Billing Impact

Within Limit:

• No additional charge
• User is added immediately

At Limit:

• Cannot invite more users
• Options:

1. Purchase User Add-Ons: Go to Billing → Add-Ons → Purchase User Add-Ons
2. Upgrade Plan: Upgrade to a plan with higher user limit

When Inviting:

• System checks canAddUser() before sending invitation
• Shows error if limit reached: "Cannot invite user. Plan allows X users. Purchase additional users or upgrade."

Removing Users - Billing Impact

User Slot Freed:

• When user is removed, their slot becomes available
• Can immediately invite a new user to fill the slot
• Note: User add-ons are not automatically refunded (they're monthly subscriptions)

Best Practice:

• Remove users before billing cycle ends if you purchased add-ons
• Then cancel user add-on subscription to avoid charges

User Add-Ons

Purchasing:

1. Go to Settings → Billing
2. Click "Add-Ons" → "User Add-Ons"
3. Enter quantity needed
4. Complete purchase
5. Add-ons added to your limit immediately

Pricing:

• Charged monthly on your billing cycle
• Prorated if purchased mid-cycle
• Cancel anytime (access until period ends)

Example:

• Professional plan (10 users)
• Purchase 5 user add-ons ($6/user/month = $30/month)
• Total capacity: 15 users
• New users can be added up to 15

Notifications

When Invitations Are Sent

Email Notification:

• UserInvitationNotification is sent immediately when invitation is created
• Email includes:
• Invitation link (expires in 7 days)
• Company name
• Inviter's name
• Assigned role
• Expiration date

Delivery:

• Uses Laravel's notification system
• Queued (sent in background)
• Respects tenant's SMTP settings if configured

When Users Join

No Automatic Notifications:

• Business owner is not automatically notified when invitation is accepted
• Team members are not notified when new members join

Optional Enhancements:

You can add notifications by:

• Creating observers on tenant_user pivot table
• Sending notifications when users are added
• Notifying admins when new members join

Notification Channels

Current Setup:

• Email only (via UserInvitationNotification)

Can Be Extended:

• Database notifications
• Push notifications
• Slack/Discord webhooks
• Custom channels

Access Control Examples

Example 1: Business Owner Inviting Admin

Scenario: You want to give someone full access to manage your team but not billing.

Steps:

1. Go to Settings → Team
2. Click "Invite User"
3. Enter admin's email
4. Select "Admin" role
5. Send invitation
6. Admin accepts and can now:

• Invite other users
• Edit tenant settings
• Access all modules
• View/edit all records

Example 2: Inviting Guest for Read-Only Access

Scenario: You want a client or consultant to view your projects but not make changes.

Steps:

1. Invite user with "Guest" role
2. Guest accepts invitation
3. Guest can:

• View projects (if projects.view permission granted)
• View contacts/companies (if crm.view permission granted)
• Cannot create, edit, or delete anything

Example 3: Member with Limited Permissions

Scenario: Team member should only work with CRM, not projects or finance.

Steps:

1. Invite as "Member"
2. Member has basic permissions by default
3. Can be customized via role manager:

• Grant: crm.view, crm.create, crm.edit
• Revoke: projects.view, finance.view

Best Practices

User Management

1. Start Small: Begin with essential team members
2. Use Appropriate Roles: Don't make everyone admin
3. Regular Reviews: Periodically review team access
4. Remove Promptly: Remove users who leave the company
5. Monitor Limits: Track user count vs. plan limits

Security

1. Principle of Least Privilege: Give users minimum permissions needed
2. Role-Based Access: Use roles instead of individual permissions when possible
3. Regular Audits: Review who has access to what
4. Secure Invitations: Only send invitations to trusted email addresses

Billing Management

1. Plan Ahead: Purchase add-ons before you need them
2. Monitor Usage: Check user count regularly
3. Remove Before Renewal: Remove unused users before billing cycle
4. Understand Limits: Know your plan's user limit
5. Upgrade When Needed: Consider upgrading plan if frequently hitting limits

Troubleshooting

Can't Invite User

Check:

1. User limit: Settings → Team shows available slots
2. Email validity: Ensure email address is correct
3. Existing invitation: Check for pending invitation to that email
4. User already in tenant: User may already be a member

Solution:

• Purchase user add-ons if at limit
• Cancel/resend existing invitation if needed
• Check team list for existing user

Invitation Not Received

Check:

1. Spam folder: Invitation emails sometimes end up in spam
2. Email address: Verify correct email address
3. SMTP settings: Check tenant SMTP configuration
4. Email queue: Check if queue is processing

Solution:

• Resend invitation
• Check email logs
• Verify SMTP configuration

User Can't Access Module

Check:

1. Module active: Verify module is enabled for tenant
2. User role: Check user's role
3. Role permissions: Verify role has required permissions
4. Subscription plan: Check if plan includes the module

Solution:

• Enable module in tenant settings
• Assign appropriate role
• Grant permissions to role
• Upgrade subscription if needed

Permission Denied Errors

Check:

1. User role in tenant
2. Permissions assigned to role
3. Module access for tenant
4. Resource ownership (for "own" vs "all" permissions)

Solution:

• Review user's role and permissions
• Grant necessary permissions
• Check resource ownership if using "own" permissions

Related Documentation

• Team Management - Basic team management guide
• Billing & Subscriptions - Subscription management
• Account Settings - User profile settings
• Security Settings - Security configuration

Updated on: 13/03/2026