What are scopes?

A scope is a metadata property associated with a client’s OAuth access token (also known as a Bearer Token). When a request to an API resource is made, MURAL's API evaluates the client application's permission to complete that request.

Calls to an API resource are authenticated using an access token obtained via the OAuth authorization flow.

When a resource is requested, MURAL's API checks the access token scope against the resource's scope requirements. If the scopes do not match, the call will return a 403 (forbidden) error.

Think of scopes as different-colored hats. In the following example, the API authentication process is represented by a guard at a security checkpoint. Jon and Max are tokens, and the hats they wear are their assigned scopes.

  • Jon has a blue hat (blue scope).
  • Max has a red hat (red scope).

The guard at the checkpoint only allows tokens with red scopes through. Max may enter, but Jon is denied access.

MURAL scopes comprise a resource type and a read or write permission. For example, a scope of rooms:read means that the token permits access to room data at a read-only level.

List of scopes and what they do

Scopes are defined when an API is created.

Read Scopes

Scope

Description

rooms:read

Retrieve information about a workspace's rooms and room settings.

users:read

Retrieve information about users, such as whether they have member, guest, or visitor permissions.

workspaces:read

Retrieve information about workspaces, including workspace settings and properties.

murals:read

Retrieve information about murals from a room and/or workspace.

identity:read

View a user's name, avatar, and company information.

templates:read

Retrieve a workspace's custom template names, descriptions, categories, and more.

Write Scopes

Scope

Description

rooms:write

Create, update, and delete rooms and their properties.

murals:write

Create murals (blank or from a template). Manage settings and widgets.

templates:write

Create a template from a mural or delete templates.

Making changes to scopes

🚧

Warning

Changing an app's scopes after an app is installed can affect the user experience.

Here's how changes to scopes affect the end-user experience with an app:

  • When a user installs an app, the user grants access for the app's scopes as they are defined at that time.

  • If additional scopes are enabled, users of the installed app will be asked to grant additional permissions for the new scopes.

  • If existing scopes are disabled, users of the installed app will not be asked to change permissions.

  • Scopes will remain active for installed copies of the app even if disabled in the app settings.

  • To completely stop an app from using any previously defined scopes, you must delete the app from My Apps.


What’s Next

Ready to update your app's scopes? Great!

Did this page help you?