Advanced permissions: backend infrastructure#

plans-img Available on all plans

deployment-img Cloud and self-hosted deployments

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.

Entity definitions#

Permissions#

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.

Roles#

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.

Scope#

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.

Context#

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#

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#

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.

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_channel_contents

channel

Read the contents of 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_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.

manage_post_bleve_indexes_job

system

Manage the status of a Bleve post indexing job.

manage_data_retention_job

system

Manage the status of a data retention job.

manage_compliance_export_job

system

Manage the status of a compliance export job.

manage_elasticsearch_post_indexing_job

system

Manage the status of an Elasticsearch post indexing job.

manage_elasticsearch_post_aggregation_job

system

Manage the status of an Elasticsearch post aggregation job.

manage_ldap_sync_job

system

Manage the status of an LDAP synchronization job.

add_bookmark_public_channel

channel

Add bookmarks to a public channel.

add_bookmark_private_channel

channel

Add bookmarks to a private channel.

edit_bookmark_public_channel

channel

Make changes to bookmarks in a public channel.

edit_bookmark_private_channel

channel

Make changes to bookmarks in a private channel.

delete_bookmark_public_channel

channel

Delete bookmarks in a public channel.

delete_bookmark_private_channel

channel

Delete bookmarks in a private channel.

order_bookmark_public_channel

channel

Reorder bookmarks in a public channel.

order_bookmark_private_channel

channel

Reorder bookmarks in a private channel.

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.

Built-in roles#

The System Scheme is built-in to the product, and its roles are defined as BuiltIn: true in the Roles table. You can use the Mattermost API to retrieve a list of permissions by role name.

The following built-in roles and associated permissions are available:

channel_admin

  • manage_private_channel_members

  • read_public_channel_groups

  • use_channel_mentions

  • create_post

  • use_group_mentions

  • add_reaction

  • read_private_channel_groups

  • remove_reaction

  • manage_public_channel_members

  • manage_channel_roles

  • add_bookmark_public_channel

  • edit_bookmark_public_channel

  • delete_bookmark_public_channel

  • order_bookmark_public_channel

  • add_bookmark_private_channel

  • edit_bookmark_private_channel

  • delete_bookmark_private_channel

  • order_bookmark_private_channel

channel_guest

  • read_channel

  • read_channel_contents

  • add_reaction

  • remove_reaction

  • upload_file

  • edit_post

  • create_post

  • use_channel_mentions

channel_user

  • manage_public_channel_properties

  • use_group_mentions

  • add_reaction

  • delete_private_channel

  • manage_private_channel_members

  • read_private_channel_groups

  • delete_public_channel

  • read_public_channel_groups

  • use_channel_mentions

  • read_channel

  • read_channel_contents

  • delete_post

  • get_public_link

  • remove_reaction

  • manage_public_channel_members

  • upload_file

  • manage_private_channel_properties

  • create_post

  • edit_post

  • add_bookmark_public_channel

  • edit_bookmark_public_channel

  • delete_bookmark_public_channel

  • order_bookmark_public_channel

  • add_bookmark_private_channel

  • edit_bookmark_private_channel

  • delete_bookmark_private_channel

  • order_bookmark_private_channel

system_admin

  • manage_others_slash_commands

  • sysconsole_write_user_management_permissions

  • edit_brand

  • remove_reaction

  • manage_incoming_webhooks

  • sysconsole_write_user_management_groups

  • create_public_channel

  • manage_private_channel_members

  • sysconsole_write_authentication

  • join_private_teams

  • create_post_ephemeral

  • list_users_without_team

  • sysconsole_write_reporting

  • join_public_channels

  • invite_guest

  • list_private_teams

  • sysconsole_write_user_management_channels

  • manage_others_bots

  • read_user_access_token

  • add_user_to_team

  • view_members

  • edit_post

  • demote_to_guest

  • delete_others_posts

  • sysconsole_write_plugins

  • delete_private_channel

  • sysconsole_read_user_management_system_roles

  • sysconsole_read_user_management_users

  • revoke_user_access_token

  • read_others_bots

  • read_public_channel_groups

  • sysconsole_write_user_management_teams

  • sysconsole_write_billing

  • convert_public_channel_to_private

  • remove_user_from_team

  • manage_team

  • add_reaction

  • manage_oauth

  • list_team_channels

  • create_team

  • read_jobs

  • invite_user

  • manage_shared_channels

  • remove_others_reactions

  • manage_remote_clusters

  • sysconsole_write_user_management_users

  • sysconsole_read_experimental

  • sysconsole_write_compliance

  • edit_others_posts

  • assign_bot

  • manage_bots

  • manage_others_outgoing_webhooks

  • manage_system_wide_oauth

  • delete_others_emojis

  • manage_others_incoming_webhooks

  • promote_guest

  • sysconsole_write_experimental

  • sysconsole_read_plugins

  • create_group_channel

  • sysconsole_read_environment

  • manage_roles

  • use_channel_mentions

  • manage_public_channel_properties

  • manage_channel_roles

  • get_public_link

  • sysconsole_read_billing

  • sysconsole_write_integrations

  • download_compliance_export_result

  • manage_slash_commands

  • assign_system_admin_role

  • create_post

  • delete_post

  • create_direct_channel

  • list_public_teams

  • create_post_public

  • read_private_channel_groups

  • sysconsole_read_integrations

  • read_other_users_teams

  • manage_jobs

  • sysconsole_read_site

  • manage_outgoing_webhooks

  • sysconsole_write_environment

  • manage_system

  • sysconsole_read_user_management_permissions

  • manage_public_channel_members

  • sysconsole_write_about

  • import_team

  • sysconsole_write_user_management_system_roles

  • sysconsole_read_reporting

  • upload_file

  • read_channel

  • read_channel_contents

  • sysconsole_read_user_management_teams

  • delete_emojis

  • manage_private_channel_properties

  • view_team

  • sysconsole_read_user_management_groups

  • create_private_channel

  • create_bot

  • join_public_teams

  • delete_public_channel

  • read_public_channel

  • sysconsole_read_about

  • read_bots

  • sysconsole_read_authentication

  • edit_other_users

  • sysconsole_read_user_management_channels

  • convert_private_channel_to_public

  • use_group_mentions

  • create_user_access_token

  • sysconsole_write_site

  • manage_team_roles

  • sysconsole_read_compliance

  • create_emojis

  • manage_post_bleve_indexes_job

  • manage_data_retention_job

  • manage_compliance_export_job

  • manage_elasticsearch_post_indexing_job

  • manage_elasticsearch_post_aggregation_job

  • manage_ldap_sync_job

  • add_bookmark_public_channel

  • edit_bookmark_public_channel

  • delete_bookmark_public_channel

  • order_bookmark_public_channel

  • add_bookmark_private_channel

  • edit_bookmark_private_channel

  • delete_bookmark_private_channel

  • order_bookmark_private_channel

system_custom_group_admin

  • create

  • edit

  • delete

  • manage members

  • restore

system_guest

  • create_group_channel

  • create_direct_channel

system_manager

  • sysconsole_write_user_management_permissions

  • sysconsole_read_about

  • sysconsole_read_user_management_channels

  • join_private_teams

  • delete_private_channel

  • view_team

  • read_jobs

  • sysconsole_read_user_management_teams

  • sysconsole_read_plugins

  • manage_channel_roles

  • manage_public_channel_members

  • remove_user_from_team

  • sysconsole_read_environment

  • list_private_teams

  • manage_private_channel_members

  • manage_private_channel_properties

  • edit_brand

  • add_user_to_team

  • convert_public_channel_to_private

  • read_private_channel_groups

  • sysconsole_write_environment

  • manage_jobs

  • sysconsole_read_reporting

  • read_public_channel

  • manage_team

  • read_channel

  • convert_private_channel_to_public

  • sysconsole_read_integration

  • read_public_channel_groups

  • list_public_teams

  • manage_team_roles

  • sysconsole_read_user_management_groups

  • manage_public_channel_properties

  • sysconsole_write_user_management_groups

  • sysconsole_read_user_management_permissions

  • sysconsole_write_site

  • sysconsole_read_site

  • sysconsole_write_user_management_channels

  • sysconsole_write_integrations

  • delete_public_channel

  • sysconsole_write_user_management_teams

  • join_public_teams

system_post_all

  • create_post

  • use_channel_mentions

  • use_group_mentions

system_post_all_public

  • create_post_public

  • use_group_mentions

  • use_channel_mentions

system_read_only_admin

  • sysconsole_read_compliance

  • read_other_users_teams

  • sysconsole_read_reporting

  • list_private_teams

  • sysconsole_read_experimental

  • read_jobs

  • read_public_channel

  • view_team

  • sysconsole_read_user_management_users

  • sysconsole_read_plugins

  • sysconsole_read_user_management_teams

  • read_public_channel_groups

  • sysconsole_read_user_management_channels

  • sysconsole_read_user_management_permissions

  • sysconsole_read_about

  • download_compliance_export_result

  • read_channel

  • sysconsole_read_authentication

  • sysconsole_read_site

  • list_public_teams

  • sysconsole_read_integrations

  • read_private_channel_groups

  • sysconsole_read_environment

  • sysconsole_read_user_management_groups

system_user

  • list_public_teams

  • join_public_teams

  • create_direct_channel

  • create_group_channel

  • view_members

  • create_team

  • create_emojis

  • delete_emojis

system_user_access_token

  • create_user_access_token

  • read_user_access_token

  • revoke_user_access_token

system_user_manager

  • manage_public_channel_members

  • sysconsole_write_user_management_groups

  • manage_private_channel_properties

  • read_channel

  • sysconsole_read_authentication

  • manage_private_channel_members

  • read_jobs

  • view_team

  • sysconsole_read_user_management_groups

  • list_private_teams

  • join_public_teams

  • manage_team

  • list_public_teams

  • add_user_to_team

  • sysconsole_read_user_management_channels

  • sysconsole_write_user_management_teams

  • read_public_channel

  • sysconsole_read_user_management_permissions

  • manage_public_channel_properties

  • join_private_teams

  • convert_public_channel_to_private

  • manage_channel_roles

  • sysconsole_read_user_management_teams

  • convert_private_channel_to_public

  • read_public_channel_groups

  • delete_public_channel

  • remove_user_from_team

  • manage_team_roles

  • delete_private_channel

  • sysconsole_write_user_management_channels

  • read_private_channel_groups

team_admin

  • remove_user_from_team

  • manage_others_slash_commands

  • manage_team_roles

  • manage_public_channel_members

  • use_group_mentions

  • manage_others_outgoing_webhooks

  • manage_slash_commands

  • manage_team

  • manage_others_incoming_webhooks

  • manage_channel_roles

  • read_public_channel_groups

  • convert_private_channel_to_public

  • remove_reaction

  • delete_post

  • manage_outgoing_webhooks

  • use_channel_mentions

  • manage_incoming_webhooks

  • delete_others_posts

  • read_private_channel_groups

  • create_post

  • manage_private_channel_members

  • convert_public_channel_to_private

  • add_reaction

  • import_team

  • add_bookmark_public_channel

  • edit_bookmark_public_channel

  • delete_bookmark_public_channel

  • order_bookmark_public_channel

  • add_bookmark_private_channel

  • edit_bookmark_private_channel

  • delete_bookmark_private_channel

  • order_bookmark_private_channel

team_guest

  • view_team

team_post_all

  • create_post

  • use_group_mentions

  • use_channel_mentions

team_post_all_public

  • use_group_mentions

  • create_post_public

  • use_channel_mentions

team_user

  • invite_user

  • add_user_to_team

  • list_team_channels

  • join_public_channels

  • read_public_channel

  • view_team

  • create_public_channel

  • create_private_channel

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