Permissions model

heliana uses role-based access control (RBAC) within each organization. Every member holds a role, and that role determines what they can see and do. The model has two layers: four built-in system roles that cover the needs of most teams, and custom roles for when you need finer-grained control.

System roles

Four roles ship with every heliana organization and cannot be edited or deleted through the UI:

Owner — complete control over the organization, including the ability to delete it entirely. An owner can manage members, servers, triggers, bans, roles, roster lists, notes, and every other resource — plus a layer of dynamic access control over the organization itself that no other role holds, not even Admin. Typically this is the organization creator.

Admin — the same broad set of permissions as Owner, minus organization deletion and that dynamic access control. Suitable for trusted co-administrators who need full operational capability without holding the keys to the organization itself.

Viewer — read-only access across all resources. A viewer can see players, bans, triggers, servers, and events, but cannot create, modify, or delete anything.

Clan leader — read access to Player Lists only. This is the role for a clan lead who needs to see the roster without the broader visibility Viewer gets into bans, players, and servers.

Custom roles

Custom roles let you define exactly which operations a subset of your team can perform. A moderator role might grant the ability to create bans and add notes but not manage triggers or servers. A stats reader might have access to events and player profiles but nothing else.

A custom role is defined by a set of permission keys — strings in the form resource:action, such as ban:create, note:read, or trigger:delete. When a member is assigned a custom role, they receive only the capabilities explicitly listed in that role.

Custom roles can be created and have permissions checked off in the roles matrix, but the invite dialog and the inline member role-change on the Members page only offer the four built-in roles — there’s currently no UI path to actually put a member into a custom role.

How permission keys work

Each resource in heliana — bans, players, servers, triggers, notes, roster lists, audit logs, roles, and more — supports a fixed set of actions. The common actions are read, create, update, and delete; some resources have additional specific actions like import for bans. A permission key is the pairing of resource and action: ban:import, server:read, trigger:update.

Both the API and the UI derive permission checks from the same key list. Server-side route guards and the client-side permission check evaluate the same set of keys, so the buttons the UI shows as disabled and the requests the API rejects are always consistent.

Per-trigger execution keys

Manual triggers introduce a permission that does not fit the static resource matrix: the right to execute one specific trigger. When a trigger is created, heliana generates a dynamic permission key in the form trigger:exec:<id>. This key is not part of the static resource list — it is created on the fly for that trigger, and removed when the trigger is deleted.

A custom role can be granted trigger:exec:<id> for some triggers and not others — a moderator role might be permitted to run a “squad warn” trigger but not a “permanent ban” trigger — and the execute control for a trigger simply does not appear for members whose role lacks that key. Owner and Admin can run every manual trigger regardless of the matrix; the built-in Viewer and Clan leader roles are fixed and can never hold a trigger:exec: key. See Grant per-trigger execution rights for the practical limits this creates today.

Only keys from the known static set or matching the trigger:exec: prefix are accepted when saving a role. Arbitrary strings are rejected, keeping the permission record clean.

How roles compose

A member has exactly one role in an organization. There is no merging of multiple roles: the assigned role determines the complete set of grants. If a team member needs a combination of permissions that no single built-in role provides, a custom role is how you’d express that — though see the caveat above on assigning one.

The full list of permission keys and the system-role grants is in Roles and permission keys. For managing roles and assignments in the UI, see Roles and permissions.