4. User Groups, Badges, and Permissions

This chapter is for the server’s owner and admins. It covers three tabs, all in the Server Settings group: the User Groups tab manages the sets of members used for permission management, the Badges tab manages the identifying marks shown next to members’ names, and the Permissions tab grants individual management permissions to user groups or individual members. Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, and you can open each tab from there. All three tabs require the Manage roles & groups permission. Once created, a user group can be assigned to channels and channel groups (you do this from the Channels tab; see §2), assigned to badges (see §4.2), or granted permissions on the Permissions tab (see §4.3). The owner and admins see mostly the same content on these three tabs.

4.1 User Groups

Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, then click User Groups in the Server Settings group. A user group is a set of members. Once you create one, you can assign the whole group to a private channel or give all of them a badge in one step, instead of setting it up person by person.

Tab Overview

The heading at the top of the tab is User Groups, with a Create Group button to its right. When there are no user groups yet, the page shows “No user groups yet.”

Each user group has its own card. Click the card’s header row to expand or collapse that group’s member management area. The header, from left to right:

• On the left, a colored dot and the group name.
• To the right of the name, a small source tag: System for system groups, Custom for custom groups.
• Further right, the group’s member count in small text in parentheses, for example (3).
• At the far right of the header, action icons: a pencil icon (tooltip: Edit); custom groups also have a trash can icon (tooltip: Delete).

Creating a User Group

Click Create Group next to the heading, and a small form opens in place above the list. It has two fields:

• Group Name is a single-line text box, up to 32 characters, with the pre-filled hint New Group.
• Group Color is a color picker. Click it to open your system’s color palette and choose a color. This is the group color shown in the dot on the left of the header and in other places where the group’s color appears.

At the bottom of the form are two buttons: Create (it can’t be clicked while the name is empty or while the form is being submitted) and Cancel. After you submit, the new group appears in the list.

Editing a User Group

Click the pencil icon on the right of a group’s header, and an editing area opens in place below the header. It has the same fields as when you created the group: Group Name (up to 32 characters) and the Group Color color picker. At the bottom are two buttons: Save (it can’t be clicked while the name is empty or while the form is being submitted) and Cancel. When you’re done, click Save to apply the new name and color.

Managing Group Members

Click a group’s header (avoiding the action icons on the right) to expand the group’s member management area. The small heading inside the area is Members.

For a system group, the member management area shows a line of italic text: “System group members are managed automatically by user roles.” A system group’s members are determined automatically by their roles and stay in sync as roles change.

For a custom group, the member management area lists the members currently in the group. Each row shows an avatar and a nickname, with an X icon on the right (tooltip: Remove) that removes that member from the group. When the group has no members, the area shows “No members in this group.”

Below the list is a drop-down menu. Its first option is Add member…, and the other options list the members who aren’t in this group yet, in the format “nickname (@username)”. Pick one and click Add next to it to add that member to the group (Add can’t be clicked when no member is selected or while the form is being submitted).

When a group holds permissions you don’t have (for example, it has been granted a permission you don’t have, or it has been assigned to a private channel and you don’t have the Manage channels permission), you must hold those permissions yourself before you can add or remove its members or delete it here. The Permissions tab shows the reason on that group; see §4.3.

Deleting a User Group

Click the trash can icon on the right of a custom group’s header, and a confirmation dialog titled Delete Group opens, with the text “Are you sure you want to delete this user group? Members will lose access granted through this group.”

At the bottom of the dialog are two buttons: Cancel and a red Delete button. When you click Delete, the group is removed from the server, and members who had channel access, badges, or permissions through this group lose them as well (for permissions granted to groups, see §4.3).

What User Groups Are For

The User Groups tab itself handles creating groups, naming them, choosing their colors, and adding or removing members. A user group you have created takes effect when you assign it elsewhere:

• Assign it to a private channel or a private channel group, so the whole group can see the channel at once. You do this from the Channels tab; see §2.
• Assign it to a badge, so the whole group gets the same badge at once. You do this from the badge’s holder management area; see §4.2.
• Grant it permissions, so the whole group gets the same set of management permissions at once. You do this on the Permissions tab; see §4.3.

4.2 Badge Management

Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, then click Badges in the Server Settings group. A badge is a colored identifying mark shown next to a member’s name. You can give a badge to an entire user group or to individual members.

Tab Overview

At the top of the tab is a Create Badge button. Clicking it opens the creation form in place. While the list loads, the tab shows Loading…; when there are no badges yet, it shows “No badges yet.”

Each badge has its own card. When the card isn’t being edited, its left side shows what the badge actually looks like, plus a source tag: System for system badges, Custom for custom badges. For the action buttons on the right (Badge Holders and Edit, plus Delete on custom badges), see “Badge List Items”.

Creating a Badge

The form that opens when you click Create Badge contains, from top to bottom:

• Preview: followed by a sample badge that updates in real time as you fill in the fields below, so you can see the result while you adjust it.
• Badge Name is a single-line text box, up to 32 characters.
• A row of three settings side by side: the Badge Color color picker, the Text Color color picker, and Icon. Icon contains a single-line text box, up to 10 characters, with the pre-filled hint Emoji or upload an image; you can type an emoji straight into it. Next to it is an Upload Icon button, which opens a file picker so you can choose an image file. After you choose a file, the text box shows the file name and temporarily can’t be used, and a “✕” clear button appears next to it so you can cancel the file selection.
• A row of two checkboxes, Show background and Show name, both checked by default. The first decides whether the badge has a background frame around it; the second decides whether the badge shows its name text.
• Two buttons at the bottom: Create (it can’t be clicked while the badge name is empty) and Cancel.

Badge List Items

The action buttons on the right of each badge card:

• Badge Holders — opens this badge’s assignment area at the bottom of the tab (see “Assigning Badges”). While the area is open, this button is highlighted in a different color.
• Edit — turns this card into an editing form in place, with the same fields as the creation form (badge name up to 32 characters, badge color, text color, icon text box up to 10 characters plus upload, and the two checkboxes for showing the background and the name), with Save and Cancel at the bottom.
• Delete — appears on custom badge cards. Click it, and a confirmation asks “Are you sure you want to delete this badge?” Confirm, and the badge is deleted.

System badges are applied by the system automatically to members who meet the conditions.

Assigning Badges

When you click a badge’s Badge Holders button, the badge’s assignment area opens at the bottom of the tab. The area’s title is “Badge Holders: {badge name}”, and a Close button at the top right collapses the area.

For a system badge, the assignment area shows a line of italic text: “System group members are managed automatically by user roles.” System badges are applied by the system automatically; this area only shows who currently holds the badge.

For a custom badge, the assignment area offers two ways to give out the badge:

• Individual assignment — a drop-down menu at the top. Its first option is – Grant Badge –, and the other options list the members who don’t hold this badge yet, in the format “nickname (@username)”. Pick one and click the Grant Badge button next to it (it can’t be clicked when no member is selected) to give the badge to that member.
• Group assignment — a drop-down menu below it. Its first option is – Grant to Group –, and the other options list the user groups that this badge hasn’t been assigned to yet. Pick a group and click the Grant to Group button next to it (it can’t be clicked when no group is selected), and the whole group gets the badge at once.

Below the assignment area, the current holders are listed in two parts:

• If the badge has been given to any groups, the subheading Holder Groups lists each group on its own row with its colored dot and name, plus a Revoke button on the right that takes the badge back from that group.
• The subheading Individual Holders lists each holder on its own row with their avatar, nickname, and @username, plus a Revoke button on the right that takes the badge back from that member. When there are no individual holders, it shows “No users have this badge.”

4.3 Permissions

Click the gear icon on the right side of the tab bar (tooltip: User Settings) to open the settings panel, then click Permissions, the last item in the Server Settings group (right after User Groups). On this tab, you grant individual management permissions to user groups or individual members. People who have been granted a permission can open the matching settings tabs and carry out the matching management actions, without being promoted to admin.

Anyone who holds the Manage roles & groups permission can see this tab; the owner and admins always can.

How Roles and Permissions Relate

• A member has one of three roles: owner, admin, or member (bot accounts are labeled bot separately). To change roles, see §3.3.
• There are 12 permissions in all (see “The 12 Permissions” below). You can grant them to user groups or directly to individual members. The permissions a member holds are the ones granted to them directly, plus the ones granted to each user group they belong to.
• The owner automatically has every permission and doesn’t need to be granted any.
• The server has two system groups, and both get their members automatically from roles: Owners contains only the owner, and Admins contains the owner and all admins (both are default names, and you can rename them on the User Groups tab).
• The admin role automatically holds the Administrator permission: the Admins group has been granted the Administrator permission, and this grant is built into the system and can’t be removed.
• Holding the Administrator permission is the same as holding the other 11 permissions.

Tab Overview

From top to bottom, the tab has two sections:

• Group permissions — with this description below it (word for word): “Open a group to change what it grants its members. Changes apply immediately; members do not need to reconnect.”
• Individual member permissions — with this description below it (word for word): “Permissions granted directly to one member, outside any group.”

If the tab fails to load, it shows “Could not load permissions: {reason}” and a Retry button.

Group Permissions

This section lists every user group on the server, including the system groups. Each group has one row: on the left are the group’s colored dot and name; on the right, in order, are a small System tag (system groups only) and the number of permissions the group has currently been granted, in the format {count} permission(s).

On a newly set-up server, Admins shows 1 permission(s) (that is the Administrator permission), and Owners shows 0 permission(s).

Creating and renaming groups and adding or removing their members all happen on the User Groups tab (§4.1). Here you only adjust the permissions a group has been granted.

Individual Member Permissions

This section lists the members who have been granted permissions directly, plus any members you have newly added from the drop-down menu below who haven’t been granted anything yet. Each member has one row: on the left are their avatar and name (in the format “nickname (@username)”), and on the right is the number of permissions granted to them directly, in the format {count} permission(s). When the list is empty, it shows “No individual grants yet. Pick a member below to start.”

Below the list is a drop-down menu. Its first option is Select a member…, and the other options list the members who aren’t on the list yet, in the format “nickname (@username)”. Pick one and click Add next to it (it can’t be clicked when no member is selected). The member then appears on the list, with their permission settings area already expanded.

A member who is newly added to the list and doesn’t have any permissions yet has an X icon on the right of their row (tooltip: Remove). Clicking it only takes that row off the list; it doesn’t change any permissions. Rows for members who already hold direct grants don’t have this icon.

A member’s permission settings area checks only the permissions granted to that member directly. Permissions they get through their user groups aren’t checked here. To see those permissions, open the relevant group under Group permissions.

Permission Settings Area

Click any group row or member row, and its permission settings area expands below it; click it again to collapse it. From top to bottom, the permission settings area contains:

• When a whole group is locked, a padlock and the reason for the lock appear first, at the very top (see “Locked Permissions” below).
• For a system group, a line of text: “Members of system groups follow user roles automatically.”
• A line that shows {count} permission(s) on the left and the Apply preset: Moderator button on the right (see “Apply preset: Moderator” below). Result messages for your actions appear below this line.
• The 12 permissions, divided by category. The category subheadings are, in order, General, Server, Channels, Roles & groups, Content, Moderation, and AI. Each item is a checkbox with the permission name, and the line of small text below it is that permission’s description.

The name and description of the Administrator item are both shown in red, and a triangle exclamation-mark icon appears next to the name. Holding it is the same as being an admin, so grant it only to people you fully trust.

Granting and Revoking

Check a permission to grant it immediately, and uncheck it to revoke it immediately; there is no separate save button. While the change is being sent, that item temporarily can’t be clicked, and its checked state changes only after the server confirms. If the change fails, the permission settings area shows “Update failed: {reason}” in red.

Changes take effect immediately, and the other person doesn’t need to reconnect: when a member is granted a permission, the matching tab appears in their settings panel right away. When a permission is revoked while they have that tab open, their screen automatically switches back to My Account.

Every grant and revocation is recorded in the Audit Log (§9.4).

Apply preset: Moderator

The permission settings areas for both groups and members have an Apply preset: Moderator button. Its tooltip reads “Delete messages, kick / ban members, view the audit log.”

Clicking it grants three permissions at once: Moderate members, Moderate messages, and View audit log. Any of these that are already held are skipped. The preset is only a shortcut for checking three items at once; it isn’t a role. After you apply it, those three items are checked in the permission settings area, and you can still uncheck them one by one later.

The result appears in the permission settings area:

• Success: “Applied the “Moderator” preset.”
• All three were already held: “Every permission in the “Moderator” preset is already granted.”
• Some items failed: “{count} permission(s) could not be applied: {reason}”

This button can’t be clicked if any of the items the recipient is still missing is a permission you don’t hold yourself, or if the whole group is locked (see “Locked Permissions” below).

For example, take a member who had no permissions before. After the preset is applied, their settings panel shows the Members tab in the Server Settings group, plus the Audit Log and Banned Words tabs in the Security group; Banned Words has only the Filter Logs sub-page. Moderate messages doesn’t correspond to any settings tab; it works inside channels and forums (see “Permissions in Channels and Forums” below).

To have a member help handle rule violations, do this: select them in the drop-down menu under Individual member permissions, click Add, and then click Apply preset: Moderator in the permission settings area that opens.

Locked Permissions

Some checkboxes are dimmed and can’t be clicked, and a reason is shown (word for word):

• “Built-in system grant; it cannot be removed.” — appears only on the Administrator item of the Admins group. This item stays checked and has a padlock icon next to its name. No one (including the owner) can uncheck it.
• “You do not hold this permission, so you cannot grant or revoke it.” — appears below the description of any permission you don’t hold yourself. You can grant or revoke only the permissions you hold.
• “This group holds permissions you lack, so you cannot change what it grants.” — if a user group holds even one permission you don’t have, the group’s entire permission settings area is locked. The reason appears at the top of the permission settings area, and the group’s row also gets a padlock icon.

A user group can be locked even if it hasn’t been granted any permissions (the reason shown is again the third message above). To change the following groups, you need the corresponding permission:

• Groups assigned to a private channel or a private channel group, or added to the Editor Groups of a multi-function channel’s Note subtype or to a voice channel’s Allowed Publisher Groups: the Manage channels permission.
• Groups checked under Visible to user groups for a sticker or sound pack: the Manage expressions permission.
• Groups that have been given a badge: the Manage roles & groups permission.

To add or remove members of such a group, or to delete it, on the User Groups tab, you likewise need to hold all of its permissions.

The 12 Permissions

The permissions are listed below in the same order as in the permission settings area. The quoted text after each dash is the description exactly as it appears on screen; Administrator and Manage system are described in prose instead.

• General category
  • Administrator — Holding it is the same as being an admin: it covers the other 11 permissions, and holders can also grant permissions to others. Its name and description are shown in red, and the description reminds you to grant it only to people you fully trust (see “Permission Settings Area” above).
• Server category
  • Manage server — “General settings — server name, icon, global theme, media uploads, notifications, DMs, announcement — and the dashboard statistics.”
  • Manage system — Covers the Backup, Orphan Files, Server Update, and Server Actions sections of the Dashboard, the TURN Server tab, and the HakoSpace Improvement Program at the bottom of the Overview tab. Its description also warns that this permission is in practice close to owner level (a backup contains the entire database, and an update replaces the executable), so it shouldn’t be handed out as a routine delegation.
  • Manage security — “Registration mode, invite codes, rate limits, banned words, email settings and IP bans.”
• Channels category
  • Manage channels — “Create, edit and delete channels and categories, channel settings, private-channel members, note editors and WHIP publishers.”
• Roles & groups category
  • Manage roles & groups — “User groups and their members, permission grants, badges. Only permissions you hold can be granted, and groups holding permissions you lack cannot be changed.”
• Content category
  • Manage expressions — “Sticker packs, soundboard, themes and fonts, and their server-wide limits.”
  • Manage content — “Pages (/p/) and io apps, and the exposure of page channels.”
• Moderation category
  • Moderate members — “Kick, ban and unban members (never admins or the owner).”
  • Moderate messages — “Delete other people’s messages and pin, bypassing a channel’s send / delete / pin locks and its upload switch (not its file limits).”
  • View audit log — “Read the audit log and the banned-word log.”
• AI category (experimental; see §10)
  • Manage AI — “AI settings, tool toggles, AI logs and connection tests (except the Bash-related settings, which stay with administrator).” (“AI logs” is the Usage Log tab in §10.3.)

Permissions Required by Each Settings Tab

Each settings tab corresponds to one or more permissions, and holding any one of them lets you see that tab. When a settings group has no tabs you can see, the whole group doesn’t appear. A member with no permissions who opens the settings panel sees only two groups: User Settings and App Settings. In the list below, the permissions after the colon are what each tab requires.

Server Settings group:

• Dashboard: Manage server or Manage system (see the division below)
• Overview, Branding, Media & Uploads, Notifications, Direct Messages: Manage server
• Appearance: Manage server or Manage expressions (see the division below)
• Channels: Manage channels
• IO Apps, Page Host: Manage content
• Members: Moderate members (changing roles also requires the Administrator permission; see §3.3)
• Badges, User Groups, Permissions: Manage roles & groups
• Stickers, Sound Board: Manage expressions

Network group:

• TURN Server: Manage system

Security group:

• Registration, Rate Limiting, Email Proxy: Manage security
• Announcement: Manage server
• Audit Log: View audit log
• Banned Words: Manage security or View audit log (see the division below)

AI Settings group (experimental; see §10):

• Overview, Tool Management, Usage Log: Manage AI

Division of Permissions Within a Tab

In the tabs below, some sections have their own permission requirements:

• Dashboard: The statistics at the top and the Refresh button require the Manage server permission; the Backup, Orphan Files, Server Update, and Server Actions sections below them require the Manage system permission. If you hold only one of the two, you see only the matching sections.
• Overview: The HakoSpace Improvement Program at the very bottom also requires the Manage system permission.
• Appearance: Server Default Theme requires the Manage server permission; Theme Management and Font Management require the Manage expressions permission. If you hold only one of the two, you see only the matching sections.
• Channels: The ▤ Page type button for creating a channel appears only if you also hold the Manage content permission. Switching an existing page channel between public and private, or moving it to another channel group, also requires the Manage content permission.
• Banned Words: The Banned Words sub-page requires the Manage security permission; the Filter Logs sub-page requires the View audit log permission, and its Clear All Logs button also requires the Manage security permission. If you hold only one of the two, only that sub-page’s button appears at the top of the tab, and the tab opens directly on that sub-page.
• AI Settings group (experimental; see §10): The Bash Execution card on the Overview tab appears only for people who hold the Administrator permission. On the Tool Management tab, changing the switch on the bash_execute row (the row appears only after the Bash Execution switch on the Overview tab is turned on) requires the Administrator permission; everyone else sees a semi-transparent switch that can’t be clicked.

Permissions in Channels and Forums

The following permissions also apply directly in channels and forums:

• Administrator: People who hold it (the owner and admins are always included) can see all private channels and private channel groups and can enter the channels in them, without being assigned separately (for how assignment works, see §2.0 and §2.5).
• Moderate messages: People who hold it (the owner and admins are always included)
  • can delete other people’s messages and pin messages regardless of the Allow sending, Allow deleting, and Allow pinning settings under the channel’s Message Permissions. The “Admin+” in the descriptions of these switches means the people who hold this permission.
  • can still attach files when Allow uploads is turned off in the channel’s File space (§2.1).
  • are automatically forum admins of every forum. The “Server admin+ inherit automatically” in Forum Settings refers to them (§2.3).
• Manage channels: The ⚙️ button at the top-right of a forum channel, which opens Forum Settings, appears only for people who hold this permission (§2.3).

The AI bot (experimental) also works according to permissions: when Member Access is off, only people who hold the Administrator permission (the owner and admins are always included) can talk to it. Which tools it can use when it acts for a member depends on the permissions that member holds, and a few tools are available only when the owner personally uses it. For details, see §10.1 and §10.2.