Scopes
You'll see the word "widgets" throughout this guide. Widgets are the same as objects in Mural. For more information on objects, see our Objects in Mural support article.
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.
Updated almost 2 years ago