App Permission System

Each feature available in the Apps-Engine is mapped to a permission. Adding the permission in the app's manifest (app.json file) will unlock said feature to be used by the app. For example, if you add the send messages permission to your app's manifest, your app can send messages in the Rocket.Chat server. If your app tries to send a message without having the send messages permission listed in the manifest, Apps-Engine will block the feature, and the app will not be able to perform the desired action.

When installing an app, be it via the Marketplace or installing it manually via zip file, a window asks the user to review the permissions that the app requires to work properly. The user installing the app can either accept and install the app or deny the permissions and not install it.

Add permissions to your app

In your app's manifest file (app.json), add the field permissions. It receives a list containing all the permissions that you are asking for. For example:

{
...
"permissions": [
    {
        "name": "user.read"
    },
    {
        "name": "user.write"
    },
    {
        "name": "upload.read"
    },
  ],
...
}

List of permissions

Here is a list of the permissions that you need to add to your app:

Permission	Description
user.read	Access user information
user.write	Modify user information
upload.read	Access files uploaded to the server
upload.write	Upload files to the server
server-setting.read	Access settings in the server
server-setting.write	Modify settings in the server
room.read	Access room information
room.write	Create and modify rooms
role.read	Access user roles
role.write	Modify user roles
message.read	Access messages
message.write	Send and modify messages
moderation.read	Access to read moderation dashboard information
moderation.write	Modify moderation dashboard information
threads.read	Access threads. Effectively allows the app to read all messages in a thread
livechat-status.read	Access Livechat status information
livechat-custom-fields.write	Modify Livechat custom field configuration
livechat-visitor.read	Access Livechat visitor information
livechat-visitor.write	Modify Livechat visitor information
livechat-message.read	Access Livechat message information
livechat-message.write	Modify Livechat message information
livechat-message.multiple	Access to read multiple messages at once
livechat-room.read	Access Livechat room information
livechat-room.write	Modify Livechat room information
livechat-department.read	Access Livechat department information
livechat-department.write	Modify Livechat department information
livechat-department.multiple	Access to read multiple departments at once
env.read	Access minimal information about the server environment
cloud.workspace-token	Access to request the workspace access token to interact with Rocket.Chat's Cloud Systems
ui.interact	Interact with the UI (UIKit)
ui.registerButtons	Use UIKit buttons
scheduler	Register and maintain scheduled jobs
networking	Register and maintain scheduled jobs
persistence	Store internal data in the database
slashcommand	Register new slash commands
video-conference.read	Access to read video conference information
video-conference.write	Modify video conference information
video-conference-provider	Act as a video conference provider in Rocket.Chat
api	Register new HTTP endpoints
oauth-app.read	Access OAuth information
oauth-app.write	Modify OAuth information

For an example of how these permissions are used in apps, refer to the Action Buttons topic.

Default permissions

Out of the permissions listed above, the following permissions are present by default to ensure backward compatibility for apps that were developed before the permission system was introduced.

    user.read,
    user.write,
    
    upload.read,
    upload.write,
    
    ui.interaction,
    
    setting.read,
    setting.write,
    
    room.read,
    room.write,
    
    message.read,
    message.write,
    
    livechat-department.read,
    livechat-department.write,
    
    livechat-room.read,
    livechat-room.write,
    
    livechat-message.read,
    livechat-message.write,
    
    livechat-visitor.read,
    livechat-visitor.write,
    
    livechat-status.read,
    
    livechat-custom-fields.write,
    
    scheduler.default,
    networking.default,
    persistence.default,
    env.read,
    command.default,
    
    videoConference.provider,
    videoConference.read,
    videoConference.write,
    
    apis.default

Once an app is on the Rocket.Chat workspace, it goes through several lifecycle phases unique to Rocket.Chat. The phases depend on the capabilities that your app has. To learn about the app lifecycle, head over to the next page.