Create a Role

Goal: define a permission set — installer, homeowner, guest, viewer — that you can assign to users.

GEM uses role-based access control (RBAC). A role is a list of rules that allow or deny access to UIs, routes, and API functions. Users can hold multiple roles, and permissions are additive — a user gets the union of all their roles' grants.

Before you start

• You're logged in as an administrator.
• You know roughly what this role should and shouldn't reach (the admin section? remote access? privileged commands?).

Steps

1. Open Roles and click Add.

   Open Roles

2. Role Name — lowercase_with_underscores (e.g. installer, homeowner, viewer).

   :::warning The name is permanent A role's name is tied to user assignments and cannot be changed after creation. Pick it carefully. :::

3. Rules — the permissions, written as allow/deny over ui, route, and api targets. A few patterns:

   Goal	Rules
   Full access (admin)	allow ui *, allow route *, allow api *
   Everything except the admin section	allow ui *, allow route *, deny route /admin*, allow api *
   Read-only-ish viewer	allow ui *, allow route *, deny route /admin*

   deny rules win where they overlap an allow, which is how you carve exceptions out of a broad grant.

4. Allow Remote — when off, the role only works on the local network and is blocked from external IPs. Turn it off for installer/admin roles you want to be on-site only.

5. Elevated — when on, the role bypasses admin-only API protection (a wildcard API grant) and can send commands to Elevated devices and run Elevated macros. Grant this only to trusted administrative roles — see how the flag gates macros in Build a Macro.

6. Save.

Verify it

Assign the role to a test user (see Create a User), log in as them, and confirm they can reach what they should — and can't reach what they shouldn't.

Related

• Create a User — assign this role to people.
• Concepts → RBAC — how socket events are auto-enumerated into permissionable API actions.
• Roles in the Admin Reference.