> ## Documentation Index
> Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Users & Roles

> How to manage users and configure tenant-scoped RBAC roles and permissions

# Users & Roles

Manage users within your organization and configure roles and permissions using tenant-scoped RBAC (Role-Based Access Control).

<Note>
  **Scope**: Tenant-scoped; requires org admin permissions\
  **Availability**: Not available in SuperAdmin
</Note>

## Understanding Tenant-Scoped RBAC

### Role Scopes

Roles are scoped to different levels:

* **SYSTEM**: Platform-level roles (SuperAdmin only - not in this documentation)
* **TENANT**: Organization-level roles (this documentation)
* **LOCATION**: Location-specific roles (this documentation)

**Customization Tier**: SYSTEM\_FIXED (cannot be changed)

### Role Hierarchy

Roles follow a hierarchy:

1. **TENANT\_PEOPLE**: Baseline role (all authenticated users)
2. **TENANT\_USER**: Standard user role
3. **TENANT\_MANAGER**: Operations manager role
4. **TENANT\_ADMIN**: Full tenant administration

**Customization Tier**: TEMPLATED\_OVERRIDE (pack provides role templates, you can create custom roles)

### Location-Scoped Roles

Roles can be assigned at:

* **Organization Level**: Applies to all locations
* **Location Level**: Applies only to specific location

## Managing Users

### Adding Users

1. Navigate to **Admin** → **Users & Roles**
2. Click **Add User**
3. Enter:
   * **Email**: User email address
   * **Name**: User name
   * **Role**: Assign default role
   * **Locations**: Assign to locations (optional)
4. Click **Send Invitation**

### User Roles

Users can have multiple roles:

* **Default Role**: Organization-wide default role
* **Location Roles**: Location-specific roles
* **Additional Roles**: Additional role assignments

### Managing User Access

1. Find user in user list
2. Click **Edit** on user
3. Update:
   * **Roles**: Add/remove roles
   * **Locations**: Assign to locations
   * **Status**: Activate/deactivate user
4. Save changes

## Roles and Permissions

### Role Templates

Industry packs provide role templates:

**Healthcare Pack:**

* WARD\_USER
* OR\_USER
* PHARMACY\_MANAGER
* CENTRAL\_STORE\_MANAGER
* QUALITY\_USER

**Retail Pack:**

* STORE\_ASSOCIATE
* STORE\_MANAGER
* DC\_MANAGER
* ANALYST

**Manufacturing Pack:**

* QC\_USER
* COMPONENT\_STORE\_USER
* PRODUCTION\_MANAGER
* RMA\_MANAGER

**Customization Tier**: TEMPLATED\_OVERRIDE (pack provides templates, you can create custom roles)

### Creating Custom Roles

1. Navigate to **Admin** → **Users & Roles** → **Roles**
2. Click **Create Role**
3. Configure:
   * **Name**: Role name
   * **Description**: Role description
   * **Scope**: TENANT or LOCATION
   * **Permissions**: Assign permissions
4. Save role

### Permission Categories

Permissions are organized by category:

* **Inventory**: View, adjust, cycle count permissions
* **Shipments**: Create, receive, track shipments
* **Forecasting**: Create scenarios, apply events
* **Planning**: View and execute recommendations
* **Admin**: Organization administration
* **Finance**: Financial data access
* **Trust**: Trust and traceability features

### Assigning Permissions

1. Open role configuration
2. Navigate to **Permissions** tab
3. Select permissions to assign:
   * **Category**: Select permission category
   * **Permissions**: Check permissions to assign
4. Save permissions

## People Directory

### Managing People

The People directory manages:

* **People Records**: Person information
* **User Links**: Links people to user accounts
* **Contact Information**: Phone, email, address

### People vs Users

* **People**: Person records (can exist without user account)
* **Users**: User accounts (must link to person)

## Role Assignment Patterns

### Organization-Wide Roles

Assign roles at organization level:

* Applies to all locations
* User has same permissions everywhere
* Simplest pattern

### Location-Specific Roles

Assign roles at location level:

* Applies only to specific location
* User has different permissions per location
* More granular control

### Mixed Roles

Combine organization and location roles:

* Default org-wide role
* Additional location-specific roles
* System uses highest permission level

## What Success Looks Like

### User Management Success

* ✅ All users have appropriate roles
* ✅ Users can access needed features
* ✅ Location-scoped roles properly assigned
* ✅ User access changes take effect immediately
* ✅ User management process documented

### Role Configuration Success

* ✅ Roles align with business needs
* ✅ Permissions properly assigned
* ✅ Role hierarchy clear
* ✅ Custom roles documented
* ✅ Role templates used when appropriate

## Common Pitfalls

### 1. Not Understanding Role Scopes

**Problem**: Assigning SYSTEM roles or not understanding TENANT vs LOCATION scopes.

**Solution**: Understand role scopes:

* SYSTEM roles are SuperAdmin only (not available to tenants)
* TENANT roles apply organization-wide
* LOCATION roles apply to specific locations

**How to avoid**: Review role scope documentation before assigning roles.

### 2. Over-Permissioning Users

**Problem**: Giving users more permissions than needed.

**Solution**: Follow principle of least privilege:

* Assign minimum permissions needed
* Use role hierarchy appropriately
* Review permissions regularly

**How to avoid**: Make permission review part of user onboarding.

### 3. Not Using Location Roles

**Problem**: Using only organization-wide roles when location roles would be better.

**Solution**: Use location roles when:

* Users need different permissions per location
* Location-specific access control needed
* Granular permission control required

**How to avoid**: Consider location roles during role design.

### 4. Not Documenting Custom Roles

**Problem**: Creating custom roles without documenting purpose and permissions.

**Solution**: Document all custom roles:

* Purpose of role
* Permissions assigned
* When to use role
* Who should have role

**How to avoid**: Make documentation part of role creation workflow.

## Troubleshooting

### User Can't Access Features

**Symptoms**: User has role but can't access expected features.

**Possible causes:**

1. Role doesn't have required permissions
2. Location role not assigned for specific location
3. Permissions not properly configured
4. Role assignment not active

**Steps to resolve:**

1. Check user's role assignments
2. Verify role has required permissions
3. Check location-specific role assignments
4. Verify role assignment is active
5. Review effective permissions

### Role Changes Not Taking Effect

**Symptoms**: Role or permission changes not reflected for user.

**Possible causes:**

1. Changes not saved
2. User session not refreshed
3. Cache issue
4. Database sync issue

**Steps to resolve:**

1. Verify changes were saved
2. Have user log out and back in
3. Clear browser cache
4. Check database for role assignments
5. Contact support if issue persists

### Can't Create Custom Role

**Symptoms**: Unable to create custom role or assign permissions.

**Possible causes:**

1. Insufficient permissions
2. Role creation not enabled
3. System constraint
4. Validation error

**Steps to resolve:**

1. Check user has tenant admin permissions
2. Verify role creation is enabled
3. Review validation errors
4. Check system constraints
5. Contact support if needed

***

## Related Pages

* [Admin Overview](/govern/overview)
* [Customization Model](/govern/customization-model)
* [Organization Settings](/govern/organization-settings)

***

## Permissions & Roles

<Warning>
  Managing users and roles requires tenant admin permissions. Role changes affect user access immediately. All roles and permissions are tenant-scoped and not available in SuperAdmin.
</Warning>