Create and Manage Scoped Roles

Quick Setup

Create or update a role in your organization or hotel in about 5 minutes.

This guide helps you create, edit, and review roles within your permitted scope.

Quick Reference

Task	Where to go	Result
Create without a template	Create New Role → Start from scratch	Opens a blank role with no copied permissions
Use a template	Create New Role	Prefills role details and permissions
Copy a listed role	Roles row actions	Opens the creation form with that role selected
Edit a role	Roles row actions → Edit	Saves permitted changes to the existing role
Manage an assignment	Account Management → Permissions	Changes or removes a staff role in the selected context
Find an action	Search features or actions…	Searches feature names, action-first descriptions, or permission codes
Review access	Selected actions only and Review changes	Shows current selections and added or removed access
Reset edits	Reset to source role	Restores the selected source values
Save the copy	Create Role	Creates an independent custom role
Find assigned users	Roles row actions → View assigned users	Opens filtered account results for that role
Delete an unused scoped role	Roles row actions → Delete Role	Removes an unassigned custom role from the catalog

Before You Start

• Sign in with Superadmin access, or use a manager role with user:permissions.
• Confirm the source role has the permissions you need.
• Decide whether the new role applies globally, to an organization, or to one hotel.

Organization and hotel managers can manage only roles owned by their permitted context. They cannot create or edit roles for another hotel or grant permissions above their ceiling. The role catalog shows only roles available for the selected organization or hotel. Scoped permission catalogs show only permissions currently supported by AVA. Retired permissions do not appear in new role forms or assignment choices.

Global templates

Global templates remain available as starting points when your access allows them. Copying a template creates an independent role in the scope you select.

Independent copy

The new role has no ongoing connection to its source role. Changes to either role do not update the other role.

Edit a Global Built-In Role

You can edit a persisted built-in role when its scope is global. AVA keeps the role global while saving your changes. The edit form lets you change Role Name, Description, and Permissions. The Role Scope field is locked for global built-in roles.

1. Go to Superadmin → Permissions → Roles, or open the roles area available to your manager account.

2. Find the global built-in role you want to change.

3. Click Edit.

4. Update Role Name, Description, or Permissions.

5. Confirm Role Scope remains Global.

6. Click Update Role.

   ✓ AVA saves the changes to the existing global built-in role.

Keep the built-in role global

Do not change a built-in role to an organization or hotel scope. AVA rejects scope changes for built-in roles. Non-global built-in roles cannot be edited.

Create a Role Without a Template

You can create a scoped role without copying an existing role.

1. Go to Superadmin → Permissions → Roles.

2. Click Add New Role.

3. Choose Start from scratch.

4. Enter the role details and select the permissions you need.

5. Choose the permitted Role Scope and assignment.

6. Click Create Role.

   ✓ AVA creates a custom role with only the permissions you selected.

Choose a Role Template

1. Go to Superadmin → Permissions → Roles.

2. Click Add New Role.

3. Open Start from an existing role.

4. Search for a system or custom role.

5. Select the role you want to use as your starting point.

   ✓ AVA pre-fills the role name, description, scope, assignment, and permissions.

The copied name starts with Copy of. The permission list uses canonical colon-delimited keys, such as admin:billing.

Copy a Role Directly from the Roles List

You can start from a specific role without opening the blank form.

1. Find the source role in the Roles list.

2. Click Create based on this role.

3. Review the pre-filled details and permissions.

   ✓ The same creation form opens with that role selected as the source.

Tailor the New Role

1. Edit Role Name and Description.

2. Choose a Role Scope.

3. Select an Organization or Hotel when the scope requires one.

4. Select or clear actions in the grouped permission editor.

5. Review the feature explanations and action-first descriptions.

6. Review the inherited, added, and removed permission counts.

7. Confirm the selected permissions do not exceed your permitted grants.

8. Click Create Role.

   ✓ AVA saves a new custom role with your edited permission set.

Review scope carefully

Changing the scope clears the selected organization or hotel. Select the required assignment again before saving.

Edit a Scoped Role

You can edit a custom role when it belongs to your organization or hotel scope. You can change its name, description, and permissions within your permitted grant ceiling.

1. Open the Roles list for the current organization or hotel.

2. Find the custom role and click Edit.

3. Review the role scope and current assignments.

4. Update the Role Name, Description, or Permissions.

5. Click Update Role.

   ✓ AVA saves the role only when its scope and permissions remain permitted.

Scope and permission limits

AVA rejects changes to roles outside your current context. It also rejects permissions above your own permitted grant ceiling.

Delete an Unassigned Scoped Role

You can delete a custom role owned by your organization or hotel. The role must have no assigned accounts.

1. Open the Roles list for the current organization or hotel.

2. Find the custom role and review its assigned-account count.

3. If users are assigned, click View assigned users.

4. Reassign or remove every listed account.

5. Return to the Roles list and click Delete Role.

6. Confirm the deletion.

   ✓ The unused role leaves the available role catalog.

Roles with assignments cannot be deleted

Reassign or remove every account first. Built-in, global, non-owned, and out-of-scope roles cannot be deleted.

Find Users Assigned to a Role

Use the role action when you need to review or change every user assigned to one role.

1. Open the Roles list for the current organization or hotel.

2. Find the role and click View assigned users.

3. Review the account list filtered to that role.

4. Use Filter by Hotel when you need to narrow organization results.

5. Change or remove assignments from Account Management.

   ✓ AVA keeps the selected role and hotel filters while you review the results.

Exact role filtering

The account list sends the selected role filter before pagination. This keeps results limited to users assigned to that role.

Assign or Remove a Staff Role

Use Account Management → Permissions to manage an employee’s role assignment. You need user:permissions access, and you can manage only permitted assignments.

1. Open Account Management in the organization or hotel context.

2. Find the staff member and click Permissions.

3. Select Organization access or a specific Hotel access entry.

4. Choose a role from the available catalog.

5. Click Update Role.

   ✓ AVA updates the selected assignment and keeps assignments outside your context unchanged.

To remove an assignment, select it, click Remove Role, and confirm. AVA protects your own current role and rejects changes outside your permitted scope.

Organization and hotel transitions

Changing between organization and hotel access can replace the employee’s current access type. Review the confirmation before saving. Independent hotel assignments remain separate when the selected context allows them.

Use scoped roles when adding staff

Account creation and invitations use the same scope rules as role assignment. The role choices refresh when you select an organization or hotel.

1. Open Account Management.

2. Select Add Account or Invite User.

3. Choose Organization access or Hotel access.

4. For hotel access, select each hotel and choose its role separately.

5. For organization access, choose an organization role.

6. Select Create Account or Send Invite.

   ✓ AVA excludes roles from hotels outside your permitted scope.

Change the scope before choosing a role

Changing the selected hotel clears its role choice. Wait for the refreshed role list, then choose the role again.

Find and review permissions

The permission editor groups actions by feature. Each feature starts collapsed so you can scan the role quickly.

1. Open a feature to review its explanation and available actions.

2. Use Search features or actions… to search descriptions or technical permission codes.

3. Use the Feature filter to show one feature.

4. Select Selected actions only to hide unselected actions.

5. Use a feature checkbox to select or clear every action in that feature.

6. Expand Review changes to check added and removed access.

   ✓ Each current permission has a direct description of the action it allows. Technical permission codes remain underneath for support and troubleshooting.

Existing permissions

Permissions outside the current catalog are retired permissions. You can edit, revoke, replace, or delete a stale role to clean it up. Remove retired permissions before assigning that role to another account.

AVA uses translated or API-provided descriptions when available. If neither description resolves, AVA shows a localized Unrecognized permission message. The message includes a readable permission code instead of an internal translation key.

Manage Video Call access

Video Call permissions appear in the Communication category. Assign them independently when a staff member needs only part of the Video Call workflow.

Permission	Access granted
video_call:settings:manage	View and change entry points, schedules, and related settings
video_call:activity:read	View Video Call activity and transcripts
video_call:activity:manage	View activity and transcripts, recall calls, and run activity analysis
video_call:device_pairing:manage	Manage account-owned AVA Alarm device pairing controls

Built-in Owner and Hotel Manager roles include all four permissions. Custom roles include only the actions you select.

General Settings permissions no longer grant Video Call access. Use dedicated permissions for every custom role that needs Video Call. video_call:activity:read allows viewing only. video_call:activity:manage also allows recall and activity analysis. Signed-in staff can still pair their own mobile device when account pairing is available.

1. Open the role editor from Superadmin → Permissions → Roles.

2. Search for Video Call or open Communication.

3. Select the actions the role needs.

4. Review the changes, then click Create Role or Update Role.

   ✓ The role receives only the selected Video Call capabilities.

Manage Phone AI and Voice Translation access

Phone AI and Voice Translation permissions appear in the Communication category. Assign them independently when a staff member needs one feature without broad Settings access.

Permission	Access granted
phone_ai:read	Open Phone AI and review call activity and transcripts
phone_ai:manage	Configure, test, and activate Phone AI
voice_translation:read	View the Voice Translation setting
voice_translation:manage	Change the Voice Translation setting

Each manage permission also grants its matching read permission. Read access does not grant management access. General Settings permissions do not grant these new feature permissions.

1. Open the role editor from Superadmin → Permissions → Roles.

2. Search for Phone AI or Voice Translation.

3. Select the actions the role needs.

4. Review the changes, then click Create Role or Update Role.

   ✓ The role receives only the selected Phone AI and Voice Translation capabilities.

Review a role without editing it

You can open a role’s details to review its access without changing the role.

1. Go to Superadmin → Permissions → Roles.

2. Find the role you want to inspect.

3. Click View permissions.

4. Review the permission breakdown grouped by feature.

   ✓ The details view shows the role description, assigned account count, and granted actions.

Reset or Replace the Starting Role

You can reset edits or select a different source role before saving.

Reset edits

1. Click Reset to source role.

2. Review the confirmation message.

3. Click Reset role.

   ✓ The form returns to the selected source role's details and permissions.

Select a different source

1. Open the role template search field.

2. Select another role or choose Start from scratch.

3. Review the confirmation message.

4. Click Use this role or Start from scratch.

   ✓ AVA replaces the form values only after you confirm.

Unsaved edits

Selecting another source can replace your name, description, scope, assignment, and permissions. Cancel the confirmation if you need to keep your edits.

What You See → Fix

Role templates are still loading

What you see: The template field shows Loading available role templates....

Fix: Wait for the role list to finish loading, then search again. If loading fails, create a blank role and select permissions manually.

Your edits disappear after changing the source

What you see: Your form shows another role's details after choosing a source.

Fix: Cancel the confirmation before changing the source. If you confirmed, re-enter the edits or use the correct source role again.

A copied role has the wrong scope

What you see: The copied role targets the source role's organization or hotel.

Fix: Choose the correct Role Scope. Then select the required Organization or Hotel before creating the role.

A copied permission appears missing

What you see: A permission from a legacy role does not appear in the permission catalog.

Fix: Confirm the permission is retired and remove it from the copied role. Save the role, then reopen it to verify the current permissions.

AVA excludes retired permissions from new roles and role assignments.

A permission description is unrecognized

What you see: A permission shows Unrecognized permission and a readable code.

Fix: Review the permission code and keep the permission if the access is expected. Contact support if you cannot identify the access it grants.

You cannot create or edit the selected role

What you see: AVA hides the role action or rejects the save.

Fix: Confirm you have user:permissions access. Switch to the organization or hotel that owns the role, then retry. Ask a higher-level administrator if you need a broader scope or permission grant.

A role assignment is rejected

What you see: AVA rejects Update Role or Remove Role.

Fix: Confirm the employee and selected assignment belong to your current context. Do not change your own current role. Choose a role from the available catalog, then retry.

If the role contains a retired permission, edit the role and remove that permission first. Then save the role and retry the assignment.

Delete Role is disabled

What you see: Delete Role is disabled, or AVA says the role is assigned.

Fix:

1. Click View assigned users for that role.
2. Reassign or remove each listed account.
3. Return to the role list after the assigned count reaches zero.
4. Retry Delete Role.

Role deletion is rejected

What you see: AVA rejects deletion with a scope or ownership message.

Fix: Confirm the role is a custom role owned by your current organization or hotel. Switch to the owning context, then retry.

The role list is empty after changing hotels

What you see: No role appears after you select a different hotel, or the list briefly refreshes.

Fix: Wait for the hotel-specific roles to load. If the list stays empty, confirm the hotel is within your scope. Then close and reopen the account or invitation form.

AVA keeps previously loaded role results visible during background refresh. This helps you continue reviewing roles while the latest results load.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Role templates never finish loading
• ❌ Confirmed changes do not appear after saving
• ❌ The new role has incorrect permissions or scope

Include the source role name, new role name, screenshot, and time of the issue.

Related Guides

• Role Permissions Not Saving
• Set Up Multi-Property Access
• Set Up Your Account