Advanced Permissions: Backend Infrastructure

This document outlines the backend server infrastructure for permissions in Mattermost and is recommended only for technical Admins or developers looking to make modifications to their installation.


The contents of this document apply to Mattermost Server version 5.0 and later.

Entity Definitions


A permission describes a permitted action which may be carried out on an object. It describes the action that users may perform in the context in which they have been assigned the role granting the permission.


A role is something to which permissions are granted, that is then assigned to users in contexts in order to grant them the assigned permissions in that context. One user may end up with different sets of permissions granted by different roles in different contexts.


Permissions live within a given scope. There are three scopes in the Mattermost system: System, Team and Channel. Permissions cascade down the scopes from the context in which they are applied. For example, if a “Channel” scoped permission is applied to a “Team” context, the permission applies to any channels within that team. A permission is considered,

  • System scope if it makes sense only on the system level. For example, manage_oauth.
  • Team scope if it makes sense at the team level and system level. For example, create_public_channel.
  • Channel scope if it makes sense at channel, team and system level. For example, manage_public_channel_properties.


A context is an instance of a scope. For example, a channel called “Developers Hangout” is an instance of channel scope. Contexts have hierarchical relationships between them that reflect the hierarchical ordering of scopes. Each context has one parent, and may have multiple children, with the ultimate parent context being the system context:

  • A channel context has a parent team context, whose parent is the system context. For example, the “Developers Hangout” channel is the channel context, with parent team context “Contributors Team”, with parent system context.
  • A team context has a parent system context and child channel contexts. For example, the “Contributors Team” is the team context, with parent system context, and with children channel contexts such as “Developers Hangout”, “Reception” and “Marketing”.

When determining whether a user is allowed to carry out a given action in a given context, the union of the permissions of all roles that user has been assigned in the current context and its parent contexts is calculated. This enables permissions to cascade down the scope hierarchy. For example, if a users is granted the manage_public_channel_properties permission in a role in the system context, then the user has permissions to manage public channel properties in all channels, in all teams, of which they are a member.


Schemes describe the default roles applied to users in a context, and all child contexts. Schemes are either defined specifically for a context, or if they are not specified, the relevant parts of the parent context’s scheme are applied, ultimately climbing the hierarchy to the System Scheme, which serves the purpose of providing the system-wide defaults. For example, if Team A does not have a team-scoped scheme defined, the System Scheme will provide the defaults for all contexts in Team A.

Additionally, the lowest-scoped scheme always takes precedence in the context. For example, if Team B has a team-scoped scheme, that scheme takes precedence over the System Scheme defaults for all contexts in Team B.

Data Structure


Permissions in Mattermost are a property of the server code base and are not created or modified dynamically. The current set of permissions are as described in the table below.

Mattermost Permissions

Name (i18n) Scope Description
invite_user team Invite users to the team using Send Email Invite or Get Team Invite Link.
add_user_to_team team Add existing server users to the current team.
use_slash_commands channel Use slash commands.
manage_slash_commands system Create, edit, and delete your own slash commands.
manage_others_slash_commands system Edit or delete other users’ slash commands.
create_public_channel team Create public channels.
create_private_channel team Create private channels.
manage_public_channel_members channel Manage public channel members.
manage_private_channel_members channel Manage private channel members.
assign_system_admin_role system Grant other users the System Admin role.
manage_roles system Manage other users’ system-wide roles.
manage_team_roles team Add and remove team members.
manage_channel_roles channel Add and remove channel members.
manage_system system Access to System Console.
sysconsole_read_usermanagement_system_roles system View system roles.
sysconsole_write_usermanagement_system_roles system Add, remove, and assign system roles.
create_direct_channel system Open Direct Message channels.
create_group_channel system Open Group Message channels.
manage_public_channel_properties channel Edit public channel name, header, and purpose.
manage_private_channel_properties channel Edit private channel name, header, and purpose.
list_public_teams system View public teams listed in the “Join Another Team” menu accessed from the main menu.
join_public_teams system Join public teams listed in the “Join Another Team” menu accessed from the main menu.
list_private_teams system View private teams listed in the “Join Another Team” menu accessed from the main menu.
join_private_teams system Join private teams listed in the “Join Another Team” menu accessed from the main menu.
list_team_channels team List public channels in a team.
join_public_channels team Join public channels.
delete_public_channel channel Archive public channels.
delete_private_channel channel Archive private channels.
edit_other_users system Edit values on the user object of other users.
read_channel channel View posts in a channel.
read_public_channel team View and access public channels on a team.
add_reaction channel Add emoji reactions to posts.
remove_reaction channel Remove emoji reactions from posts.
remove_others_reactions channel Remove other users emoji reactions from posts.
permanent_delete_user (deprecated) system Permanently delete other users.
upload_file channel Upload file attachments to posts.
get_public_link system Get permalink for posts.
manage_incoming_webhooks team Create, edit, and delete your own incoming webhooks.
manage_outgoing_webhooks team Create, edit, and delete your own outgoing webhooks.
manage_others_webhooks(deprecated) team Edit and delete other users’ incoming or outgoing webhooks.
manage_others_incoming_webhooks team Edit and delete other users’ incoming webhooks.
manage_others_outgoing_webhooks team Edit and delete other users’ outgoing webhooks.
manage_oauth system Create, edit, and delete your own OAuth 2.0 apps.
manage_system_wide_oauth system Edit or delete other users’ OAuth 2.0 apps.
create_post channel Post in channels.
create_post_public channel Create a system message within a channel.
create_post_ephermal channel Create an ephemeral message within a channel.
edit_post channel Authors edit their own posts. Edit post time limit is controlled by the "PostEditTimeLimit" config.
edit_others_posts channel Edit other users’ posts.
delete_post channel Authors delete their own posts.
delete_others_posts channel Delete other users’ posts.
remove_user_from_team team Remove users from team.
create_team system Create teams.
manage_team team Access Team Settings.
import_team system Import teams in Team Settings.
view_team team Read the Team object.
create_bot team Create bot accounts.
assign_bot team Assign bots to users other than who created the bot.
read_bot team View own bots created.
read_others_bots team View bots created by others.
manage_bots team Edit and delete own bots.
manage_others_bots team Edit and delete bots created by others.
view_members team List all members on the team.
list_users_without_team system List users without a team.
create_user_access_token system Create user access tokens.
read_user_access_token system Read user access tokens by ID.
revoke_user_access_token system Revoke user access tokens.
manage_jobs system Create and cancel jobs.
create_emojis team Create custom emoji.
delete_emojis team Delete own custom emoji.
delete_others_emojis team Delete custom emoji created by others.
invite_guest system Invite guest users via email invite or add existing guests to teams.
promote_guest system Promote guests to member users.
demote_to_guest system Demote member users to guests.
manage_remote_clusters system Add, remove, and view remote clusters for shared channels.

Roles Field

Roles are applied to objects that represents that user’s membership in a context. These are referenced in the Roles field of the User, TeamMember, ChannelMember and Schemes Tables.

In the TeamMember and ChannelMember tables, it’s the Roles field that contains custom roles and the SchemeAdmin and SchemeUser booleans that indicate the member object should inherit the respective roles from the relevant scheme, either the default or custom scheme assigned to the relevant team.

Roles Table

Roles are dynamic and user configurable, necessitating a database table with the following fields:

  • Id (Autoincrement, Primary Key)
  • Name (Unique String with Character Constraints, e.g. “team_user”).
  • Display Name (String)
  • Description (String)
  • Permissions (String): Space-separated permissions names
  • Scheme Managed (bool): Indicates whether this role is managed as part of a scheme.
  • BuiltIn (bool): Indicates if this role is built in to the Mattermost system and not removable by the user.

The System Scheme is built in to the product and it’s roles are defined as BuiltIn: true in the Roles table.

Schemes Table

Schemes are dynamic and user configurable, necessitating a database table with the following fields:

  • Id (Autoincrement, Primary Key)
  • Name (Unique String with Character Constraints, e.g. “corporate_scheme”)
  • Display Name
  • Description (String)
  • Scope (String): Team or Channel
  • Team Admin Role (String): Empty if Channel Scope
  • Team User Role (String): Empty if Channel Scope
  • Team Guest Role (String): Empty if Channel Scope
  • Channel Admin Role (String): Always provided
  • Channel User Role (String): Always provided
  • Channel Guest Role (String): Always provided