Permissions model

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

System roles

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

Owner — holds every key in the matrix. The organization’s creator holds it from the start; the invite dialog never offers it, but the role selector in the Members table does, and only the Owner can assign it, and assigning it transfers ownership: the previous Owner becomes an Admin. An organization has exactly one Owner, who can be neither removed nor demoted.

Admin — holds every key Owner holds except organization:delete: deleting the organization and paying for it (checkout, the billing portal, changing the number of extra servers) stay with Owner. The other difference is not a key: the last remaining owner can be neither removed nor demoted.

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 automations 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 automation:delete. When a member is assigned a custom role, they receive only the capabilities explicitly listed in that role.

Custom roles are created and have permissions checked off in the roles matrix, and the invite dialog and the inline member role-change on the Members page offer them next to Admin; the inline role-change also offers Owner, the invite dialog does not. Every organization is seeded with one custom role named Moderator at creation. It holds no automation:* key; it runs the moderation buttons through links to those automations instead (see the roles and permission keys reference).

How permission keys work

Each resource in heliana — bans, players, servers, automations, notes, access lists, tags, 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 manage for access lists and tags (create or edit one, add or remove entries). A permission key is the pairing of resource and action: access:manage, server:read, automation:update.

Not every key is checked yet: ban:update and member:create can be granted, but nothing in heliana checks them, so granting or withholding those two has no effect. See Roles and permission keys for the full, current breakdown of which keys are actually enforced.

Both the API and the UI derive permission checks from the same key list. The server 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 for the keys that are enforced.

Server access

Besides the role, every member has server access: All servers or a chosen set of servers. It is set in the invite dialog and in the Server access column of the Members table. It narrows what a member sees to objects tied to their servers, whatever their role: an object is visible when its servers overlap the member’s access, and editable only when all of its servers lie inside it. Objects with no servers are not narrowed, and an object that covers the whole organization is editable only by a member with no restriction.

The right to run one automation

The right to run one specific manual automation does not fit the resource matrix, and no dynamic key is generated for it. A key is resource:action, and a key per automation cannot exist in that set — so this right is a second axis alongside the matrix instead.

The Run button of a manual automation opens for either of two independent reasons: the caller’s role holds automation:update, which opens every manual automation in the organization, or the caller’s role is linked to that one automation, which opens only the automation named. A custom role can therefore be linked to a “squad warn” automation but not to a “permanent ban” automation; where the role has neither the key nor the link, the run control does not appear at all.

Owner and Admin hold automation:update and run every manual automation by the key. system-role columns are locked, so only a custom role carries links. On the Roles screen the two axes are one checkbox per automation in the Automation actions rows; a saved role carries them as two separate fields, its keys and its linked automations. See Grant per-automation execution rights for how to set it up.

A key that is not in the matrix is not quietly dropped when a role is saved — the whole save is refused. No role holds such a key, so it always exceeds the set of whoever is saving, and the request comes back with “You can only grant what your own role already has” and nothing written. Discarding does happen, but in two other places: the role editor drops keys it does not recognize before sending, and permission resolution ignores a key that is still in an old role record but no longer in the matrix.

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.

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.