Permissions

Discord allows defining permissions for each application command in a specific guild or at the global level. Global permissions, or Default Member Permissions, control the permissions a guild member must have to execute the command by default.

Guild-level permissions, or Permission Overrides, are used to further customize command permissions on a per-guild basis. To set these overrides, your bot needs a Bearer token with the “applications.commands.permissions.update” OAuth2 scope from a user in the guild with the “Manage Roles” and “Manage Guild” permissions. Handling this is mostly outside the scope of this library, although a few helpers are provided. Consult the Discord documentation for more information.

Permissions can only be set on top-level commands. If you set a permission on a command group, it will be applied to all subgroups and subcommands within.

Default member Permissions

This field represents a permission integer like it is used in channel overwrites and role permissions and determines the permissions a guild member needs to have in order to execute that command.

Let’s say you want to have a /setup command that is locked to members who have the permissions to manage channels and to manage roles. The permission integer for this case would be 268435472. A helping hand to calculate that permissions can be found here.

By simply putting the number shown above into the default_member_permissions, the command is locked.

@discord.command(default_member_permissions=268435472)
def setup(ctx):
    "Only members with channel- and role-managament permissions can run this"

    return "You have the right permissions! Setting up now..."

Setting specific overwrites

Warning

The methods below will require an extra oauth scope granted by a server admin as of discord’s rewrite of slash command permissions. If you can, it’s recommended to use the default_member_permissions field instead.

This library provides methods to get and set permission overwrites: DiscordInteractions.get_permission_overwrites() and DiscordInteractions.set_permission_overwrites(), respectively.

Setting the permission overwrites requires the application ID, guild ID, command ID, Bearer token, and relevant Permission list. To accommodate a variety of application architectures, there are several ways to pass in these parameters.

  • The Application ID can be either retrieved from a flask.Flask object bound to the DiscordInteractions instance, the app parameter, or by manually providing application_id and base_url.

  • The Guild ID must be specified with guild_id.

  • The Command ID can be either retrieved from a Command or by manually providing command_id.

  • The Bearer token can be either provided with token, or the bot’s token can be used if the method has access to the flask.Flask app. Note that there are some caveats to this.

  • For the setting method, the Permission objects must be supplied with the permissions parameter.

# Without the app or instance, useful in a background worker
DiscordInteractions.get_permission_overwrites(
    guild_id=...,
    command_id=...,
    token=...,
    application_id=...,
    base_url=...,
)

# With the instance and app passed in, useful in an app-factory project
discord.get_permission_overwrites(
    guild_id=...,
    command=...,
    token=...,
    app=...,
)

# With the instance and a bound app, using an implicit token
# useful in most small projects
discord.get_permission_overwrites(
    guild_id=...,
    command=...,
)

Caveats of using the bot’s own token for permission overwrites

If the token is omitted, the bot’s token will be used. Note that this only works if the bot’s developer account is an admin in the guild. This is handy for small bots on your own servers, but you shouldn’t rely on this for anything you want others to use in their servers.

You’ll also need to explicitly add the applications.commands.permissions.update scope:

app.config[
    "DISCORD_SCOPE"
] = "applications.commands.update applications.commands.permissions.update"

Permission class

The Permission class accepts a role ID, user ID, or channel ID, and represents a permissions override for that role, user, or channel.

class flask_discord_interactions.Permission(role=None, user=None, channel=None, allow=True)

An object representing a single permission overwrite.

Permission(role='1234') allows users with role ID 1234 to use the command

Permission(user='5678') allows user ID 5678 to use the command

Permissoin(channel='9012') allows users in channel ID 9012 to use the command

Permission(role='3456', allow=False) denies users with role ID 3456 from using the command

Parameters:

  • role (str) – The role ID to apply the permission to.

  • user (str) – The user ID to apply the permission to.

  • channel (str) – The channel ID to apply the permission to.

  • allow (bool) – Whether use of the command is allowed or denied for the specified criteria.

dump()

Returns a dict representation of the permission.

Returns:

A dict representation of the permission.

Return type:

dict

classmethod from_dict(data: dict)

Returns a Permission object loaded from a dict.

Parameters:

data (dict) – A dict representation of the permission.