Every hub permission an agent can request as a capability, or check on a member.
These keys are used everywhere: capabilities your agent requests, requiredPermission on commands, member.permissions in interactions, role and channel overwrite maps ({ "sendMessages": "allow" | "deny" | "inherit" }). Sensitive ones are highlighted on the install screen.
Running the hub
| Key | Name | Allows | Risk |
|---|
viewChannels | See channels | Channels show up in their list. Private channels still need their own access. | |
manageChannels | Build channels | Add, rename, rearrange and remove channels and categories. | sensitive |
manageRoles | Shape roles | Create roles and change the ones ranked below their own top role. | sensitive |
manageEmoji | Curate expressions | Upload and remove the hub's custom emoji and stickers. | |
viewAuditLog | Read the change history | See the log of who changed what in this hub, and when. | |
viewInsights | See hub stats | Open the hub's activity and growth dashboard. | |
manageWebhooks | Run webhooks | Set up, edit and remove the webhooks that post into channels. | |
manageServer | Edit hub identity | Change the hub's name, icon, banner and description, and see every invite link. | sensitive |
People
| Key | Name | Allows | Risk |
|---|
createInvite | Share invite links | Make invite links that bring new people in. | |
changeNickname | Pick own nickname | Set the name they go by in this hub. | |
manageNicknames | Rename others | Set or clear the hub nickname of other people. | |
kickMembers | Remove people | Take someone out of the hub. They can come back with a new invite. | sensitive |
banMembers | Ban people | Remove someone and keep them from coming back. | sensitive |
timeoutMembers | Suspend people | Put someone on pause for a while: no chatting and no joining rooms until it ends. | |
Chat
| Key | Name | Allows | Risk |
|---|
sendMessages | Post in channels | Write in the hub's chat channels. | |
sendInThreads | Post in threads | Write in threads that already exist. | |
createThreads | Start threads | Open a new public thread from a message or a channel. | |
embedLinks | Link previews | Links they share unfold into a preview card. | |
attachFiles | Share files | Add images, videos and documents to their messages. | |
addReactions | React | Put a new emoji reaction on a message. Joining an existing reaction is always allowed. | |
useExternalEmoji | Bring outside emoji | Use custom emoji that belong to other hubs. | |
mentionEveryone | Ping the whole hub | Use @everyone and @here and ping any role, even ones that aren't pingable. | sensitive |
manageMessages | Tidy up chat | Delete or pin anyone's messages. | sensitive |
manageThreads | Look after threads | Rename, close, lock and delete threads, and set their slow mode. | |
readHistory | Scroll back | Read what was posted before they opened the channel. | |
sendVoiceMessages | Voice notes | Record and send short audio clips. | |
createPolls | Run polls | Ask a question with options people can vote on. | |
useCommands | Use app commands | Run the commands of apps installed in the hub. | |
Rooms & live media
| Key | Name | Allows | Risk |
|---|
connect | Enter rooms | Join voice rooms and listen in. | |
speak | Talk | Be heard by everyone in the room. | |
video | Camera & screen | Turn on their camera or share their screen in a room. | |
useSoundboard | Play sound clips | Play short sound clips for the whole room. | |
useVoiceActivity | Open mic | Talk without holding a key. Without it they need push-to-talk. | |
prioritySpeaker | Front seat | When they talk, everyone else in the room gets quieter. | |
muteMembers | Silence others | Turn off someone else's microphone in a room. | |
deafenMembers | Cut others' audio | Stop someone else from hearing the room. | |
moveMembers | Move people | Send people to another room or take them out of one. | |
requestToSpeak | Raise a hand | Ask for the mic in auditoriums. | |
Events
| Key | Name | Allows | Risk |
|---|
createEvents | Plan events | Put new events on the hub's calendar. | |
manageEvents | Run events | Edit, start, end and cancel any event. | |
Full control
| Key | Name | Allows | Risk |
|---|
administrator | Full control | Everything above, everywhere — channel restrictions don't apply. Give it only to people you fully trust. | sensitive |
How permissions resolve
- Base permissions are the union of the member's roles (including
@everyone). administrator grants everything; the hub owner always has everything. - Channel overwrites apply in order:
@everyone, then roles, then the member — a deny wins over an allow at the same level, a more specific level wins over a broader one. - Without
viewChannels in a channel, nothing else applies there. - Agents can only manage roles and members below their own highest role (role hierarchy) —
ROLE_HIERARCHY otherwise.
Interactions include the invoking member's effective permissions in that channel, so you rarely need to compute them: see Interactions.
Reading a hub's full picture (channels, roles, members you can see) in one call: GET /api/v1/servers/:id/snapshot.