Team Management

Overview

Team Management allows merchants to add staff members, assign roles, and control access to different parts of the backoffice.

Key Purpose: Manage staff access and permissions.

Purpose

This page lets you invite team members, assign them roles with specific permissions, and control which locations each user can access.

Key Concepts

Roles: Named permission sets (Owner, Manager, Staff, or custom) that determine what a user can view and do across the backoffice.
Permissions: Granular action-level controls (e.g., view-transactions, edit-items) checked on every API request; wildcard * grants full access.
Location Assignment: Users can be restricted to specific locations; an empty location list means access to all locations.
Invitation Flow: New users are created with an Inactive status and receive an email with a time-limited invite token generated via Str::random(60) that expires after OTP_EXPIRY_MINUTES.
User Statuses: A user is either Active (can log in) or Inactive (blocked from login but history is preserved).

Actions

Invite a Team Member

Enter the user's name, email, and role; the system creates an inactive account, validates the role and location assignments, and sends an invitation email.

Assign Roles and Locations

Change a user's role or update their assigned locations; you cannot assign roles to yourself as enforced by the backend.

Manage Custom Roles

Create, edit, or delete custom roles with a tailored set of permissions to match specific job functions like Kitchen Staff or Marketing.

Resend Invitation

Re-trigger the invitation email with a fresh token for users who have not yet activated their account.

Location

Backoffice Route: /settings/team
Users: /settings/team/users
Roles: /settings/team/roles
Backend Controller: app/Http/Controllers/Api/TeamController.php
Vue Component: src/views/settings/TeamUsersComponent.vue

Concepts

Users

Individual team members with login credentials.

Roles

Permission sets that define what users can access.

Permissions

Specific actions users can perform (view, create, edit, delete).

User Fields

Name

Property	Value
Field ID	`name`
Label	Full Name
Type	Text
Required	Yes
Validation	max: 100 characters

Description: Team member's full name.

Email

Property	Value
Field ID	`email`
Label	Email Address
Type	Email
Required	Yes
Validation	Valid email, unique

Description: Login email and contact address.

Business Logic:

Used for login
Must be unique across all users
Receives notifications

Phone

Property	Value
Field ID	`phone`
Label	Phone Number
Type	Phone
Required	No

Description: Contact phone number.

Role

Property	Value
Field ID	`role_id`
Label	Role
Type	Select
Required	Yes
Options	Available roles

Description: The role assigned to this user, determining their permissions.

Default Roles:

Owner: Full access to everything
Manager: Most access, no billing
Staff: Limited operational access
Custom: User-defined roles

Locations

Property	Value
Field ID	`location_ids`
Label	Assigned Locations
Type	Multi-select
Required	No
Default	All locations

Description: Which locations this user can access.

Business Logic:

Empty = All locations
Specific locations = Limited access
User only sees data for assigned locations

Active

Property	Value
Field ID	`active`
Label	Active
Type	Toggle
Default	true
Required	No

Description: Whether the user can log in.

Business Logic:

Inactive users cannot log in
Preserves user history without deleting

Two-Factor Authentication

Property	Value
Field ID	`two_factor_enabled`
Label	2FA Enabled
Type	Toggle
Default	false
Required	No

Description: Whether two-factor authentication is enabled.

Business Logic:

When enabled, requires code from authenticator app
Increases account security

Role Fields

Role Name

Property	Value
Field ID	`name`
Label	Role Name
Type	Text
Required	Yes
Validation	max: 50 characters

Description: Name of the role.

Examples:

"Manager"
"Kitchen Staff"
"Delivery Driver"
"Cashier"

Description

Property	Value
Field ID	`description`
Label	Description
Type	Textarea
Required	No

Description: Description of what this role is for.

Permissions

Property	Value
Field ID	`permissions`
Label	Permissions
Type	Permission Matrix
Required	Yes

Description: What this role can access and do.

Permission Categories

Dashboard

dashboard.view - View dashboard

Orders/Transactions

transactions.view - View orders
transactions.create - Create orders
transactions.edit - Edit orders
transactions.refund - Process refunds
transactions.cancel - Cancel orders

menus.view - View menus
menus.create - Create menus
menus.edit - Edit menus
menus.delete - Delete menus
items.view - View items
items.create - Create items
items.edit - Edit items
items.delete - Delete items
categories.view - View categories
categories.manage - Manage categories
modifiers.view - View modifiers
modifiers.manage - Manage modifiers

Marketing

loyalty.view - View loyalty
loyalty.manage - Manage loyalty
offers.view - View offers
offers.manage - Manage offers
customers.view - View customers
customers.manage - Manage customers

Settings

locations.view - View locations
locations.manage - Manage locations
payments.view - View payment settings
payments.manage - Manage payments
team.view - View team
team.manage - Manage team
billing.view - View billing
billing.manage - Manage billing

Devices

devices.view - View devices
devices.manage - Manage devices

Reports

reports.view - View reports
reports.export - Export reports

Inventory

inventory.view - View inventory
inventory.manage - Manage inventory

Default Roles

Owner

Full access to everything. Cannot be modified or deleted.

json

{
  "name": "Owner",
  "permissions": ["*"]
}

Manager

Full operational access, no billing.

json

{
  "name": "Manager",
  "permissions": [
    "dashboard.view",
    "transactions.*",
    "menus.*",
    "items.*",
    "categories.*",
    "modifiers.*",
    "loyalty.*",
    "offers.*",
    "customers.*",
    "locations.view",
    "locations.manage",
    "payments.view",
    "team.view",
    "devices.*",
    "reports.*",
    "inventory.*"
  ]
}

Staff

Limited operational access.

json

{
  "name": "Staff",
  "permissions": [
    "dashboard.view",
    "transactions.view",
    "transactions.create",
    "menus.view",
    "items.view",
    "categories.view",
    "inventory.view"
  ]
}

Business Logic

Permission Check

User attempts action
        │
        ▼
Get user's role
        │
        ▼
Check role permissions:
├── Has wildcard (*)? → Allow
├── Has specific permission? → Allow
└── No permission? → Deny (403 Forbidden)

Location Filtering

User requests data
        │
        ▼
Check user's assigned locations:
├── All locations? → Return all data
└── Specific locations? → Filter data by locations

Invitation Flow

Admin invites user
        │
        ▼
System sends invitation email
        │
        ▼
User clicks link
        │
        ▼
User sets password
        │
        ▼
Account activated

Customer Impact

Team management doesn't directly affect customers, but:

Staff with limited permissions may not be able to help with certain issues
Location-restricted staff only see their location's orders

Relations

Depends On

Locations: Users can be assigned to locations

Affects

All Features: Permissions control access
Activity Log: Actions tracked by user

Business Rules

A user's email must be unique across all users; a user already associated with a different merchant account cannot be added again.
You cannot assign roles to yourself; the backend rejects self-role-assignment with a 400 error.
The Owner role grants wildcard (*) permissions, cannot be modified, and cannot be deleted.
Invitation tokens are single-use, generated with Str::random(60), and expire after the configured OTP_EXPIRY_MINUTES period.
Location and role IDs are validated against the current vendor's actual locations and roles before any assignment is persisted.

FAQs

"Can I have multiple owners?" The Owner role is a system role with full access; additional users can be assigned the Owner role but the role itself cannot be customized.
"What happens when I deactivate a user?" The user can no longer log in, but all their historical actions and data remain intact in the system.
"Can a user belong to multiple locations?" Yes, assign multiple locations to a user; leaving the location list empty grants access to all locations.
"How do I reset a user's password?" Resend the invitation email, which generates a fresh invite token the user can use to set a new password.
"Are permission changes immediate?" Yes, once a role's permissions are updated, the change takes effect on the user's next API request.

Troubleshooting

Problem: User can't log in

Causes:

User marked as inactive
Wrong email/password
Account not yet activated
Two-factor authentication issue

Solutions:

Activate user account
Reset password
Resend invitation
Reset 2FA

Problem: User can't access feature

Causes:

Role doesn't have permission
User assigned to wrong role
Location restriction

Solutions:

Add permission to role
Assign correct role
Add location to user

Problem: User sees wrong locations

Causes:

Location assignments incorrect
New location not assigned

Solutions:

Update user's location assignments
Add new location to user

Examples

Small Business (Owner Only)

json

{
  "users": [
    {
      "name": "John Owner",
      "email": "john@restaurant.com",
      "role": "owner",
      "locations": []
    }
  ]
}

Restaurant with Manager

json

{
  "users": [
    {
      "name": "John Owner",
      "email": "john@restaurant.com",
      "role": "owner"
    },
    {
      "name": "Jane Manager",
      "email": "jane@restaurant.com",
      "role": "manager"
    }
  ]
}

Multi-Location with Location Managers

json

{
  "users": [
    {
      "name": "John Owner",
      "email": "john@chain.com",
      "role": "owner",
      "locations": []
    },
    {
      "name": "Amsterdam Manager",
      "email": "amsterdam@chain.com",
      "role": "manager",
      "locations": ["location-amsterdam"]
    },
    {
      "name": "Rotterdam Manager",
      "email": "rotterdam@chain.com",
      "role": "manager",
      "locations": ["location-rotterdam"]
    }
  ]
}

Custom Role: Kitchen Staff

json

{
  "role": {
    "name": "Kitchen Staff",
    "description": "View orders and inventory only",
    "permissions": [
      "transactions.view",
      "inventory.view",
      "inventory.manage"
    ]
  }
}

Custom Role: Marketing

json

{
  "role": {
    "name": "Marketing",
    "description": "Manage promotions and customers",
    "permissions": [
      "dashboard.view",
      "loyalty.view",
      "loyalty.manage",
      "offers.view",
      "offers.manage",
      "customers.view",
      "customers.manage",
      "reports.view"
    ]
  }
}

Team Management ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Invite a Team Member ​

Assign Roles and Locations ​

Manage Custom Roles ​

Resend Invitation ​

Location ​

Concepts ​

Users ​

Roles ​

Permissions ​

User Fields ​

Name ​

Email ​

Phone ​

Role ​

Locations ​

Active ​

Two-Factor Authentication ​

Role Fields ​

Role Name ​

Description ​

Permissions ​

Permission Categories ​

Dashboard ​

Orders/Transactions ​

Menu Management ​

Marketing ​

Settings ​

Devices ​

Reports ​

Inventory ​

Default Roles ​

Owner ​

Manager ​

Staff ​

Business Logic ​

Permission Check ​

Location Filtering ​

Invitation Flow ​

Customer Impact ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: User can't log in ​

Problem: User can't access feature ​

Problem: User sees wrong locations ​

Examples ​

Small Business (Owner Only) ​

Restaurant with Manager ​

Multi-Location with Location Managers ​

Custom Role: Kitchen Staff ​

Custom Role: Marketing ​

Team Management

Overview

Purpose

Key Concepts

Actions

Invite a Team Member

Assign Roles and Locations

Manage Custom Roles

Resend Invitation

Location

Concepts

Users

Roles

Permissions

User Fields

Name

Email

Phone

Role

Locations

Active

Two-Factor Authentication

Role Fields

Role Name

Description

Permissions

Permission Categories

Dashboard

Orders/Transactions

Menu Management

Marketing

Settings

Devices

Reports

Inventory

Default Roles

Owner

Manager

Staff

Business Logic

Permission Check

Location Filtering

Invitation Flow

Customer Impact

Relations

Depends On

Affects

Related Features

Business Rules

FAQs

Troubleshooting

Problem: User can't log in

Problem: User can't access feature

Problem: User sees wrong locations

Examples

Small Business (Owner Only)

Restaurant with Manager

Multi-Location with Location Managers

Custom Role: Kitchen Staff

Custom Role: Marketing