Roles & Permissions

Permission System

Osmium uses a bitwise permission system where each permission is represented by a bit flag. Permissions can be combined using bitwise OR operations.

Permission Flags

All available community permissions from the CommunityPermission enum:

NO_PERMISSION

No permissions granted

ADMINISTRATOR

default:"1<<0"

Full administrative access, bypasses all permission checks. Users with this permission can perform any action.

VIEW_CHANNEL

default:"1<<1"

Ability to view and read channels. Without this permission, channels are hidden.

SEND_MESSAGES

default:"1<<2"

Ability to send messages in text channels

CONNECT_VOICE

default:"1<<3"

Ability to connect to voice channels

MODIFY_CHANNEL

default:"1<<4"

Ability to edit channel settings, create new channels, and delete channels

SEND_MEDIA

default:"1<<5"

Ability to send media attachments (images, videos, files) in messages

DELETE_MESSAGES

default:"1<<6"

Ability to delete messages sent by other users

PIN_MESSAGES

128

default:"1<<7"

Ability to pin and unpin messages in channels

SPEAK_VOICE

256

default:"1<<8"

Ability to speak/transmit audio in voice channels

MODIFY_COMMUNITY

512

default:"1<<9"

Ability to edit community settings (name, photo, etc.)

MODIFY_ROLES

1024

default:"1<<10"

Ability to create, edit, and delete roles, and assign roles to members

REMOVE_MEMBERS

2048

default:"1<<11"

Ability to ban/remove members from the community

Computing Permissions

Permissions are stored as 64-bit integers. To combine permissions:

# Grant VIEW_CHANNEL and SEND_MESSAGES
permissions = (1 << 1) | (1 << 2)  # = 6

# Or using the enum values
permissions = VIEW_CHANNEL | SEND_MESSAGES  # = 2 | 4 = 6

Roles

Roles are groups with specific permissions that can be assigned to members. Each role has:

Role Structure

fixed64

Snowflake ID of the role

community_id

fixed64

Snowflake ID of the community this role belongs to

name

string

The name of the role

permissions

fixed64

Bitwise permission flags granted to this role

priority

uint32

Role priority/hierarchy. Higher values = higher priority. Used to determine which role’s color/permissions take precedence.

color

uint32

RGB color for this role (displayed next to member names)

separated

bool

Whether members with this role are displayed separately in the member list

public

bool

Whether this role is publicly assignable or admin-only

Get Roles

Retrieve all roles in a community. Method: communities.getRoles Request: GetRoles

community_id

fixed64

Snowflake ID of the community

Response: CommunityRoles

roles

CommunityRole[]

List of all roles in the community

default_permissions

fixed64

The default permission flags granted to all members (even without roles)

Create Role

Create a new role in a community. Method: communities.createRole Request: CreateRole

community_id

fixed64

Snowflake ID of the community

name

string

Name for the new role

permissions

fixed64

Bitwise permission flags to grant to this role

priority

uint32

Priority/hierarchy level for this role

color

uint32

RGB color for this role

separated

bool

Whether to display members with this role separately

public

bool

Whether this role is publicly assignable

Example:

CreateRole {
  community_id: 123456789
  name: "Moderator"
  permissions: 2246  # VIEW_CHANNEL | SEND_MESSAGES | DELETE_MESSAGES | PIN_MESSAGES
  priority: 10
  color: 0x5865F2
  separated: true
  public: false
}

Edit Role

Modify an existing role’s properties. Method: communities.editRole Request: EditRole

fixed64

Snowflake ID of the role to edit

community_id

fixed64

Snowflake ID of the community

name

string

New name for the role

permissions

fixed64

New permission flags for the role

priority

uint32

New priority level

color

uint32

New color

separated

bool

New separated setting

public

bool

New public setting

Delete Role

Permanently delete a role from a community. Method: communities.deleteRole Request: DeleteRole

fixed64

Snowflake ID of the role to delete

community_id

fixed64

Snowflake ID of the community

Edit Default Permissions

Modify the default permissions granted to all members (regardless of roles). Method: communities.editDefaultPermissions Request: EditDefaultPermissions

community_id

fixed64

Snowflake ID of the community

permissions

fixed64

New default permission flags

Permission Overrides

Channels can have role-specific permission overrides that allow or deny permissions independent of the role’s base permissions.

PermissionOverrides Structure

pos

fixed64

Bitwise flags for permissions to explicitly allow/grant

neg

fixed64

Bitwise flags for permissions to explicitly deny/revoke

Permission resolution order:

Deny overrides (neg)
Allow overrides (pos)
Role permissions
Default permissions

Get Channel Overrides

Retrieve all permission overrides for a specific channel. Method: communities.getChannelOverrides Request: GetChannelOverrides

community_id

fixed64

Snowflake ID of the community

channel_id

fixed64

Snowflake ID of the channel

Response: ChannelOverrides

overrides

ChannelOverride[]

List of all permission overrides for this channel

Create Channel Override

Create a new permission override for a role in a specific channel. Method: communities.createChannelOverride Request: CreateChannelOverride

community_id

fixed64

Snowflake ID of the community

channel_id

fixed64

Snowflake ID of the channel

role_id

fixed64

Snowflake ID of the role

permissions

PermissionOverrides

The permission overrides to apply (pos for allows, neg for denies)

Example:

CreateChannelOverride {
  community_id: 123456789
  channel_id: 987654321
  role_id: 555555555
  permissions: {
    pos: 4  # Allow SEND_MESSAGES
    neg: 32 # Deny SEND_MEDIA
  }
}

Delete Channel Override

Remove a permission override from a channel. Method: communities.deleteChannelOverride Request: DeleteChannelOverride

community_id

fixed64

Snowflake ID of the community

channel_id

fixed64

Snowflake ID of the channel

role_id

fixed64

Snowflake ID of the role whose override should be removed

Get Started

Core Concepts

Authentication

Messaging

Communities

Chats

Media & Files

Advanced Features

Permission System

Permission Flags

Computing Permissions

Roles

Role Structure

Get Roles

Create Role

Edit Role

Delete Role

Edit Default Permissions

Permission Overrides

PermissionOverrides Structure

Get Channel Overrides

Create Channel Override

Delete Channel Override

Build docs developers (and LLMs) love

Get Started

Core Concepts

Authentication

Messaging

Communities

Chats

Media & Files

Advanced Features

​Permission System

​Permission Flags

​Computing Permissions

​Roles

​Role Structure

​Get Roles

​Create Role

​Edit Role

​Delete Role

​Edit Default Permissions

​Permission Overrides

​PermissionOverrides Structure

​Get Channel Overrides

​Create Channel Override

​Delete Channel Override

Build docs developers (and LLMs) love

Permission System

Permission Flags

Computing Permissions

Roles

Role Structure

Get Roles

Create Role

Edit Role

Delete Role

Edit Default Permissions

Permission Overrides

PermissionOverrides Structure

Get Channel Overrides

Create Channel Override

Delete Channel Override