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 the dependent 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 from the Marketplace or manually using a ZIP file, you’ll be prompted to review the permissions that the app will access on your workspace. You can either accept the permissions to install the app or deny them to cancel the installation.

List of permissions

Here is a list of the permissions that you can 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

To add a permissions to your app, refer to the Add permission to your app section.

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

Add permissions to your app

To add permissions to your app, add the field permissions to your app's manifest file ( app.json). 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"
    }
  ],
...
}

Adding permissions to your app.json overrides the default permissions, so you must include all required permissions for your app to function. For an example of how these permissions are used in apps, refer to the Action Buttons topic.

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.