Skip to main content

Access control

Access control in dzbot defines who can do what on a server.

In practice, dzbot uses three layers:

  1. User rights (direct rights on a player account)
  2. Group rights (rights inherited through groups)
  3. Subscription availability (server needs to have a valid subscription to the dzbot service)

Faction-specific rights are documented in Factions concept.

How effective access is calculated​

For each player, dzbot combines:

  • Direct user rights on the player
  • Rights from all groups the player belongs to
  • Rights from all server default groups

Naming pattern used in rights:

  • <module>.<action> (for example players.whitelist, groups.edit_access_rights, settings.edit)

User rights​

User rights are explicit permissions assigned directly to a specific player.

Use user rights when:

  • one person needs an exception,
  • you need temporary elevated access,
  • you do not want to change a whole group.

Examples:

  • players.whitelist
  • restrictions.create
  • players.change_access_rights

Where to manage:

  • Admin -> Players -> Player details -> Settings tab

When to use: Only use user rights when you need a temporary exception, usually it's better to use group rights.

Group rights​

Group rights are the standard way to manage team access.

You define rights once on a group and assign players to that group. Every member inherits those rights.

Where to manage:

  • Admin -> Groups -> Group -> Settings tab -> User rights
  • Admin -> Groups -> Group -> Players tab to add/remove members

Good practice:

  • create role-based groups (for example Support, Moderator, Economy, Content)
  • keep user-level overrides minimal
  • prefer group changes for long-term access changes

Common group-level examples:

  • groups.view, groups.create, groups.edit, groups.delete
  • groups.edit_access_rights
  • groups.manage_all_places

Default groups​

Default groups are server-level baseline groups that are included in access checks for all players on that server.

This is useful for a shared baseline permission set without manually editing every individual player.

Where to manage:

  • Admin -> Settings -> Players & Access -> Default Groups

Admin-level rights​

Some rights are considered admin-level and unlock admin panel sections and operations.

There is also a full-access admin permission level for server-level rights.

Use this very carefully and only for trusted staff.

Typical high-impact examples:

  • orders.refund
  • orders.redeliver
  • server.change_plan
  • players.impersonate_player
  • admin.tickets.view
  • admin.tickets.reply
  • admin.tickets.assign

Ticket rights are split between shop access and admin access:

  • player.tickets.view lets players open Shop -> Tickets and read their own tickets.
  • player.tickets.create, player.tickets.send_message, player.tickets.close, and player.tickets.archive control player actions inside the shop ticket flow.
  • admin.tickets.view unlocks read-only access to Server Admin -> Tickets.
  • admin.tickets.reply, admin.tickets.internal_message, admin.tickets.assign, and admin.tickets.change_status are admin-only ticket rights and also count as admin-panel access.
  • admin.tickets.change_level allows moving a ticket between support levels; admin.tickets.manage_levels allows managing the levels themselves. "May move levels" is a separate question from "which levels do I see".
  • admin.tickets.manage_categories allows editing the request types and their intake forms, and publishing their Discord panels. Deliberately separate from admin.tickets.manage_levels: "may edit the faction application form" is a much weaker permission than "may rewire support-level visibility".

Support-level rights (server-dependent)​

Most rights are the same on every server. Support levels are the exception: each level of each server contributes its own right, keyed by the level's database id.

  • The key is admin.tickets.level_<id> and appears in the group and player rights editors labelled with the level's position and name.
  • Because the key hangs off the id and not the position, reordering levels never moves a permission.
  • Resolution is cumulative: the highest level position a staff member resolves wins, and every level at or below it is visible. This is deliberate — non-cumulative resolution would silently lose escalated tickets whenever someone forgot a checkbox.
  • The admin.* wildcard covers level rights like any other admin key, so full admins need no per-level grant.
  • A freshly created level is granted to nobody. Its tickets are invisible until the right is handed out, and the level management drawer warns while that is the case. Rights are never written on someone's behalf.
  • Deleting a level removes its now-dead key from every group, player and developer API key on that server.
  • A level right is not admin-panel access on its own: it says which tickets you see, so a group holding only a level right still needs an ordinary admin.tickets.* right to open the queue.
  • Reordering or dissolving levels changes what an existing right resolves to (the rule is positional), so both require access to every level — admin.tickets.manage_levels alone is not enough.
  • Impersonation compares level reach rather than exact keys: holding level 3 covers a target on level 1.

The breadcrumb row in the admin area can show a help link that opens the relevant documentation page.

This is controlled by a dedicated access right:

  • documentation.view

Recommended practice:

  • assign documentation.view to every group that has any admin panel access (moderators, support, full admins)
  • keep it out of player-only groups to avoid exposing internal help docs in the shop frontend

Subscription gate vs rights​

Rights alone are not always enough. Admin and shop access also require an active subscription.

So access can fail for two reasons:

  1. missing permission right
  2. inactive or expired subscription (admin routes redirect to Stripe manage)

If staff says "I have the right but still cannot access", verify subscription status first. Admin pages will redirect to Stripe manage while inactive.

Access check checklist​

Use this quick checklist when access does not match expectations:

"I cannot see a menu entry"​

  • Check group/user rights for the related module/action.
  • Check whether the server subscription is active.

"I can open a page but cannot perform an action"​

  • View and edit/delete/run actions are separate rights.
  • Grant the specific action right (not only module visibility rights).

"A new player has too much/too little access"​

  • Review Default Groups in server settings.
  • Check if the player has direct user-right overrides.
  1. Define a small set of role-based groups.
  2. Assign module/action rights to those groups.
  3. Use default groups for baseline onboarding.
  4. Use direct user rights only for exceptions.
  5. Review high-privilege permissions (full admin access, refunds, restrictions, major configuration changes) regularly.