Skip to main content

Roles

Roles define permission sets that control what users can access in GEM. Each role contains rules specifying which UIs, routes, and API functions are allowed or denied.

Overview​

GEM's role-based access control (RBAC) system provides flexible, granular permissions management. Roles can be assigned to multiple users, and users can have multiple roles (permissions are additive).

Viewing Roles​

The main grid displays all configured roles with the following columns:

  • ID - Unique role identifier
  • Name - Role name
  • Rules - Permission rules (displayed as array)
  • Enabled - Whether the role is active

System role (ID 0) cannot be deleted.

Grid Actions​

  • Add - Create a new role
  • Edit - Modify an existing role
  • Delete - Remove a role (except system role)
  • Reload - Refresh the grid data

Creating a Role​

To create a new role:

  1. Click Add in the grid toolbar
  2. Configure the role properties (see sections below)
  3. Click Save

Role Configuration​

Basic Information​

Role Name

  • Internal identifier (lowercase_with_underscores)
  • Examples: admin, user, installer, viewer, api_only
  • Cannot be changed after creation (tied to user assignments)

Allow Remote

  • Toggle to permit remote/internet access
  • When disabled:
    • Role only works on local network
    • Blocks access from external IPs
    • Useful for restricting installer/admin accounts to on-site only

Elevated

  • Toggle to grant elevated privilege to the role
  • When enabled:
    • Bypasses admin-only API protection — all sensitive functions are accessible via a wildcard (*) API grant
    • Can send commands to devices marked Elevated and run macros marked Elevated
    • Can read secure attributes (passwords, API keys, tokens, etc.)
    • Can write to any table via generic insert_model / update_model / delete_model / create_model / sort_model
    • Can call raw-query endpoints (query_json) and set_attribute
    • Equivalent to the legacy admin role behavior
  • When disabled (default):
    • Sensitive (admin-only) API functions must be granted by name — a wildcard * alone is not enough
    • Functions that require elevation are marked with an elevated badge in the API checklist
    • Commands and macros flagged Elevated are rejected
    • Secure attributes are filtered out of query results; sensitively-named rows are scrubbed even if mis-flagged
    • Writes via the generic handlers are limited to an allowlist (macro, macro_step, ui_macro, channel) — everything else returns not authorized
    • delete_model, set_attribute, and query_json are refused outright
  • The existing admin role is auto-elevated on startup to preserve backward compatibility
  • Use sparingly — most roles should not be elevated

Status

  • Toggle to enable/disable the role
  • Disabled roles:
    • Cannot be assigned to new users
    • Existing users lose permissions immediately
    • Configuration preserved for re-enablement

Current Rules​

Displays the compiled permission rules for this role:

allow ui *
allow route /admin*, /controls*
allow api all
deny api delete_macro

Rules are shown in a terminal-style display with syntax highlighting.

Permission Configuration​

Configure permissions using three resource types:

Resource Types:

  • User Interfaces - Which UIs users can access
  • Routes/Pages - Which web pages users can navigate to
  • API Functions - Which backend functions users can call

Resource Type: User Interfaces​

Control access to specific UIs (dashboards, control panels):

Allow UIs:

  • Check UIs the role can access
  • "all" grants access to all UIs
  • Useful for control-only roles

Deny UIs:

  • Check UIs the role cannot access
  • Overrides allow rules
  • Useful for restricting specific panels

Example:

Allow: all
Deny: admin_panel

Result: Access to all UIs except admin_panel

Resource Type: Routes/Pages​

Control access to web routes (URL paths):

Common Routes:

  • /admin* - All admin pages
  • /controls* - All control pages
  • /av* - All AV pages
  • /* - All pages
  • Specific routes: /admin/users, /controls/lighting

Allow Routes:

  • Check routes the role can navigate to
  • "all" grants access to all routes
  • Supports wildcards (*)

Deny Routes:

  • Check routes the role cannot navigate to
  • Overrides allow rules

Example:

Allow: all
Deny: /admin*

Result: Access to all pages except admin section

Resource Type: API Functions​

Control access to backend API functions:

API Functions Include:

  • get_zones - Query zones
  • command_async - Send commands
  • set_attribute - Modify attributes
  • insert_model - Create records
  • update_model - Modify records
  • delete_model - Delete records
  • backup_create - Create backups
  • 100+ other functions

Allow API:

  • Check API functions the role can call
  • "all" grants access to all functions
  • Fine-grained control for API integrations

Deny API:

  • Check API functions the role cannot call
  • Overrides allow rules

Example:

Allow: all
Deny: delete_model, backup_delete

Result: Full API access except deletions

Search Filter​

Use the search box to filter long lists of resources:

  • Type to filter UIs, routes, or API functions
  • Filters update in real-time
  • Makes finding specific resources easier

Permission Rules​

Rules are compiled into a rule array shown in "Current Rules":

Rule Syntax​

<action> <type> <resources>

Actions:

  • allow - Grant access
  • deny - Revoke access

Types:

  • ui - User interfaces
  • route - Web routes/pages
  • api - API functions

Resources:

  • Comma-separated list
  • * or all for all resources
  • Specific names/IDs

Rule Examples​

Full Admin Access:

allow ui *
allow route *
allow api *

Read-Only User:

allow ui *
allow route /controls*, /av*
allow api get_zones, get_attributes, query_async
deny api insert_model, update_model, delete_model

Installer (Local Only):

allow ui *
allow route *
allow api *
deny api delete_backup
Allow Remote: No

API Integration:

deny ui *
deny route *
allow api get_zones, command_async, get_attributes

Control Panel Only:

allow ui control_panel
allow route /controls*
allow api get_zones, command_async
deny route /admin*
deny api update_model

Rule Evaluation​

Permissions are evaluated in this order:

  1. Deny rules are checked first

    • If ANY deny rule matches, access is denied
    • Deny overrides allow

  2. Allow rules are checked next

    • If ANY allow rule matches, access is granted
    • Multiple allows are additive

  3. Default deny

    • If no rules match, access is denied
    • Explicit allows required for access

Example Evaluation:

User has roles: user, installer

user role:
  allow ui control_panel
  allow api get_zones, command_async

installer role:
  allow ui *
  allow api *
  deny api delete_backup

Combined permissions:
  allow ui * (from installer)
  allow api * (from installer)
  deny api delete_backup (from installer)

Result:
  - Can access all UIs
  - Can call all APIs except delete_backup
  - Deny rule from installer overrides allow all

Pre-Configured Roles​

GEM includes several default roles:

admin​

allow ui *
allow route *
allow api *
Allow Remote: Yes
  • Full system access
  • All permissions
  • Can access remotely
  • Use sparingly, only for administrators

user​

allow ui *
allow route /controls*, /av*, /
deny route /admin*
allow api get_zones, get_attributes, command_async, macro_async, query_async
deny api insert_model, update_model, delete_model
Allow Remote: Yes
  • Standard homeowner/occupant
  • Access to controls and AV
  • Cannot access admin section
  • Cannot modify configuration

installer​

allow ui *
allow route *
allow api *
deny api delete_backup, delete_user
Allow Remote: No
  • Full access during commissioning
  • Cannot delete critical data
  • Local network only
  • Disable after installation complete

viewer​

allow ui monitoring_panel, camera_panel
allow route /controls*, /av*
allow api get_zones, get_attributes, query_async
deny api command_async, macro_async
Allow Remote: Yes
  • Read-only access
  • Can view but not control
  • Useful for monitoring displays
  • Cannot execute commands

api_only​

deny ui *
deny route *
allow api get_zones, get_attributes, command_async, query_async, set_attribute
Allow Remote: Yes
  • API integrations only
  • No web interface access
  • Specific API functions
  • For third-party systems

Common Workflows​

Creating a Custom User Role​

  1. Click Add
  2. Name: homeowner
  3. Allow Remote: Yes
  4. Select User Interfaces resource type
  5. Allow: all
  6. Select Routes/Pages resource type
  7. Allow: /controls*, /av*, /
  8. Deny: /admin*
  9. Select API Functions resource type
  10. Allow: get_zones, command_async, macro_async
  11. Click Save

Creating a Limited Installer Role​

  1. Click Add
  2. Name: installer_limited
  3. Allow Remote: No (local only)
  4. Select User Interfaces
  5. Allow: all
  6. Select Routes/Pages
  7. Allow: all
  8. Deny: /admin/backup, /admin/users
  9. Select API Functions
  10. Allow: all
  11. Deny: delete_backup, delete_user, update_user
  12. Click Save

Creating an Integration Role​

  1. Click Add
  2. Name: home_assistant
  3. Allow Remote: Yes
  4. Select User Interfaces
  5. Deny: all (no UI needed)
  6. Select Routes/Pages
  7. Deny: all
  8. Select API Functions
  9. Allow: get_zones, get_attributes, command_async, set_attribute
  10. Click Save

Security Best Practices​

Role Design​

  1. Principle of Least Privilege: Grant minimum necessary permissions
  2. Role Segregation: Create distinct roles for different user types
  3. Avoid Over-Permissioning: Don't grant "all" unless truly needed
  4. Regular Review: Audit role permissions quarterly

Remote Access​

  1. Admin Roles: Consider local-only for admin roles
  2. Installer Roles: Always set local-only
  3. User Roles: Allow remote for legitimate users
  4. API Roles: Allow remote only if needed

Role Assignment​

  1. Multiple Roles: Be cautious with role combinations
  2. Test Permissions: Verify combined permissions work as expected
  3. Document Roles: Maintain documentation of role purposes
  4. Naming Convention: Use clear, descriptive role names

Elevated Devices & Macros​

In addition to role-level elevation, individual devices and macros can be flagged Elevated. Only users in an elevated role can:

  • Send commands to an elevated device (checked on direct device commands and on zone commands that resolve to an elevated device)
  • Run an elevated macro via the macro / stop_macro sockets or a command-form macro redirect

Server-side triggers, schedules, and macro steps run regardless of the flag — the gate is on client socket entry, not internal execution. Use this to expose scenes and routine controls to non-admin users while keeping security panels, locks, and privileged macros admin-only. See Devices and Macros for per-entity configuration.

Admin-Only Operations​

Certain sensitive API functions are restricted to users with an elevated role or an explicit (by-name) API grant. A wildcard * allow alone is not sufficient for these functions — this prevents accidental exposure when broad permissions are assigned. These include:

  • System control: restart_gem, update_gem, run_script, run_client_script
  • Backup & restore: backup_restore, backup_delete (and SFTP/B2 variants)
  • Database maintenance: perform_database_maintenance, data_retention_cleanup, apply_pending_changes
  • Encryption keys: download_encryption_keys, upload_encryption_keys
  • SSL/TLS: save_ssl_config, regenerate_ssl_certificates
  • User management: upsert_user
  • AI assistant: ai_assistant, ai_script_assistant
  • Reports: report_dashboard, report_activity, report_export
  • Network scanning: arp_scan, network_interfaces

All admin-only requests and denied requests are recorded in the Request History.

Dangerous Permissions​

These API functions should be restricted:

  • delete_model - Can delete any record
  • delete_backup - Can remove backups
  • delete_user - Can remove user accounts
  • update_user - Can elevate privileges
  • insert_model - Can create admin users
  • backup_restore - Can overwrite system
  • restart_gem - Can interrupt service

Troubleshooting​

User Cannot Access Resource​

Check:

  1. Role Assignment: Verify user has roles assigned
  2. Role Enabled: Ensure roles are enabled
  3. Allow Rules: Check if resource is allowed
  4. Deny Rules: Check if resource is explicitly denied
  5. Remote Access: If remote, verify "Allow Remote" is enabled
  6. Multiple Roles: Check combined permissions from all roles

Debug Process:

  1. Identify the resource (UI, route, or API)
  2. Check each of user's roles
  3. Verify allow rules include the resource
  4. Verify no deny rules block the resource
  5. Test with a simpler role to isolate issue

Permission Too Broad​

Symptoms:

  • User can access things they shouldn't
  • Security concern

Solutions:

  1. Review "Current Rules" section
  2. Add deny rules for specific resources
  3. Remove overly broad allow rules
  4. Consider creating new restricted role

"all" or "*" Not Working​

Explanation:

  • all is literal string for selection
  • * is the rule value meaning "all"
  • When "all" checkbox is checked, rule uses *

To Allow All:

  1. Check the "all" checkbox
  2. Rule will show: allow type *

Changes Not Taking Effect​

Role and user edits are pushed to live socket sessions automatically — connected clients pick up the new permissions without reconnecting. A role edit cascades through every user that holds the role.

If a connected client still seems to have the old permissions:

  1. Check the role is enabled — disabled roles drop from a user's permission set immediately on save.
  2. Check the user is enabled — disabling a user revokes their session and forces a fresh login.
  3. Reload the page if the UI itself was gated (route allow/deny is evaluated on navigation, not on every action).
  4. As a last resort, restart GEM to force all sessions to re-authenticate.

Cannot Delete Role​

Causes:

  1. Cannot delete system role (ID 0)
  2. Role is assigned to users

Solution:

  1. Remove role from all users first
  2. Then delete the role

Advanced Topics​

API Function Discovery​

To see all available API functions:

  1. Edit any role
  2. Select API Functions resource type
  3. Click search box
  4. All functions listed

Or query via API:

let functions = await GemApp.getInstance().getApiFunctions();

Route Discovery​

To see all available routes:

  1. Edit any role
  2. Select Routes/Pages resource type
  3. All routes listed including:
    • Static routes
    • Dynamic routes (wildcards)
    • Admin routes
    • Control routes
    • AV routes

Custom Rule Syntax​

Rules are stored as array of strings:

[
  "allow ui 1,2,3",
  "deny ui 4",
  "allow route /controls*,/av*",
  "allow api get_zones,command_async"
]

Can be manipulated programmatically for advanced scenarios.

Role Hierarchies​

GEM doesn't have built-in role hierarchies, but you can simulate:

Pattern:

  1. Create base role with minimal permissions
  2. Create enhanced roles that include base permissions
  3. Assign multiple roles to users

Example:

base_user:
  allow api get_zones, get_attributes

control_user:
  allow api command_async, macro_async
  (assign both base_user and control_user to user)

Result: User has get_zones, get_attributes, command_async, macro_async