How to Set Up Team Access with Role-Based Permissions

What You'll Need

Before setting up team access, ensure you have:

• MoltFlow Business plan — Team features require the Business tier. Starter and Pro plans support single-user access only.
• Admin access to your MoltFlow account — Only account owners and admins can invite team members and manage roles.
• Team member email addresses — You'll need valid email addresses for each person you want to invite.

Team access in MoltFlow uses role-based access control (RBAC) to ensure secure, granular permission management. This guide walks you through the complete setup process.

Step 1: Understand the Role Hierarchy

MoltFlow implements three role levels, each with distinct permissions:

Role inheritance: Each role inherits permissions from lower tiers. For example, Admins can do everything Members can do, plus manage sessions and settings.

Multi-tenant isolation: All users on your team share the same tenant. This means they access the same WhatsApp sessions, contacts, and messages — but with different permission levels. MoltFlow enforces tenant isolation at the database level, so team members can never access data from other MoltFlow accounts.

Best practices:

• Start team members as Members, upgrade to Admin only when needed (principle of least privilege)
• Limit Owner role to one or two trusted individuals (billing access is sensitive)
• Review role assignments quarterly as team responsibilities change

Step 2: Invite a Team Member

To invite a new team member:

1. Navigate to Settings > Team in the MoltFlow dashboard
2. Click the "Invite Member" button in the top-right corner
3. Enter the email address of the person you want to invite
4. Select their initial role (Owner, Admin, or Member)
5. Click "Send Invitation"

The invited user will receive an email with a signup link scoped to your tenant. When they click the link and complete signup, they're automatically added to your team with the assigned role.

Email not received? Common issues:

• Check spam/junk folder
• Verify the email address is correct (no typos)
• Some corporate email systems block automated emails — ask your IT team to whitelist @waiflow.app

Programmatic invitations: If you need to invite team members via API (e.g., syncing from your HR system), use the /users/invite endpoint:

curl -X POST https://apiv2.waiflow.app/users/invite \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member"
  }'

The API returns an invitation ID and confirmation that the email was sent.

Step 3: Assign Roles and Permissions

After a team member accepts their invitation, you can modify their role at any time:

1. Go to Settings > Team in the dashboard
2. Find the team member in the list
3. Click the role dropdown next to their name
4. Select the new role (Owner, Admin, or Member)
5. Click "Save"

What each role can and cannot do:

Owner:

• Create, connect, and delete WhatsApp sessions
• Send and receive messages on all sessions
• Modify all settings (AI, webhooks, anti-spam rules)
• Access billing and subscription management
• Invite and remove team members
• Change any user's role (including other Owners)

Admin:

• Create, connect, and restart WhatsApp sessions
• Send and receive messages on all sessions
• Modify settings (AI, webhooks, anti-spam rules)
• NO access to billing or subscription changes
• Invite and remove team members (but cannot modify Owner roles)

Member:

• View assigned WhatsApp sessions (see Step 4)
• Send messages on assigned sessions
• View contacts, groups, and message history
• NO ability to modify settings, connect sessions, or manage billing
• NO ability to invite or remove team members

Role changes take effect immediately — but the user must re-login to see the updated permissions. MoltFlow caches role information in the JWT token, so active sessions won't reflect role changes until the user logs out and back in.

Step 4: Manage Session Access Per Team Member

Business accounts can restrict which WhatsApp sessions a team member can access. This is useful when different team members handle different WhatsApp numbers (e.g., sales team uses one number, support team uses another).

To configure session access:

1. Go to Sessions in the dashboard
2. Select the session you want to configure
3. Click the "Access" tab in the session settings
4. Toggle the switch next to each team member's name to grant or revoke access
5. Click "Save Changes"

How session access works:

• Owners and Admins: By default, they have access to all sessions (you can restrict this if needed)
• Members: By default, they have NO session access until explicitly granted
• Access includes: viewing messages, sending messages, viewing contacts, managing labels

Example use case: Your company has three WhatsApp numbers — Sales (+1-555-0100), Support (+1-555-0200), and Marketing (+1-555-0300). You can configure:

• Sales team members → access only Sales session
• Support team members → access only Support session
• Marketing team members → access only Marketing session
• Admins → access all three sessions

If a Member tries to access a session they don't have permission for, they'll see a "No Access" message in the dashboard and API calls will return 403 Forbidden.

Step 5: Audit Team Activity

MoltFlow logs all team activity for compliance and accountability. To view the activity log:

1. Go to Settings > Team in the dashboard
2. Click the "Activity Log" tab
3. Filter by user, action type, or date range

The activity log captures:

• Message sends: Who sent messages, to which contacts, on which sessions
• Session changes: Who connected, restarted, or deleted sessions
• Settings modifications: Who changed AI config, webhooks, anti-spam rules
• User management: Who invited or removed team members, who changed roles

Each log entry includes:

• Timestamp (UTC)
• User email and role
• Action type (e.g., "message.sent", "session.connected", "settings.updated")
• Resource affected (e.g., session ID, contact phone number)
• IP address (for security auditing)

Why auditing matters:

• Compliance: GDPR Article 30 requires maintaining records of processing activities
• Security: Detect unauthorized access or suspicious activity
• Accountability: Track who made changes when troubleshooting issues

Technical details: MoltFlow's request logging middleware automatically captures the user_id with each API request. The middleware runs before route handlers, so all actions are logged — even failed requests.

Troubleshooting

Invitation email not received:

• Check spam/junk folder
• Verify email address (look for typos)
• Some email providers block automated emails — whitelist @waiflow.app
• Invitation links expire after 7 days — resend if expired

Role changes not taking effect:

• User must log out and back in to refresh JWT token
• Browser may cache old permissions — try incognito mode or clear cookies
• If still not working, contact support (may be a caching issue on our end)

Member can't see sessions:

• Check session access settings (Settings > Sessions > [Session] > Access tab)
• Members have NO session access by default — you must explicitly grant it
• If access is granted but still not visible, check the Member's role assignment

Team member can't accept invitation:

• Invitation link may have expired (7-day limit) — resend invitation
• Email may be already associated with another MoltFlow account — they need to use a different email
• Corporate firewall may be blocking signup page — try from home network or mobile data

What's Next?

Now that you've set up team access, explore these related guides:

• Manage Multiple WhatsApp Sessions — Run multiple WhatsApp numbers from one dashboard
• Export Data for GDPR Compliance — Respond to data export requests from customers
• Track Message Usage and Plan Limits — Monitor usage across your team

Need help? Contact support at [email protected] or visit our documentation.