Scopes provide a way to set the desired level of access to specific resources within your Mason account.
There are two types of authentication methods to access the Mason platform, each of which has a corresponding scope set:
- Users – logging into the Mason Controller
- API Keys – Programmatic access to your account via APIs or CLI
The scope sets for both methods are structured as a hierarchy, where parent scopes automatically inherit their child scopes.
As an example, a user assigned the notify:all scope will automatically be given all of the children's scopes.
Scope Granularity
To complement the principle of least privilege, Mason scopes are partitioned into logical sections by resource types, each of which can be given different permissions sets based on the desired access level. For example, if a user is responsible for moving devices between groups and no other actions within the Mason Controller – then this user should be given fleet:move and fleet:read (to access the devices list page) – and no higher than read-only in other scope sections.
For additional examples, see the “Required Scope(s) for Common Actions” section for the minimum scopes required for specific Mason Platform actions.
Suggestion
As a general rule, Mason recommends following the principle of least privilege when assigning users’ scopes and API key scopes to avoid unnecessary access to resources and/or fleet actions.
User Scopes
While logged in to Mason Controller, user scopes define the user's level of visibility and capabilities they have across different resources.
When inviting new users into your Mason Controller account, you’ll need to assign the appropriate scope set before sending the invitation. By default, the read-only scope presets will be selected, but can be modified to the admin preset or customized to the desired level of access.
Note: A user must be assigned the user:admin scope to invite a new user or modify an existing user’s scope set.
API Key Scopes
Similar to user scopes, the API key scope set defines the key’s level of access when calling Mason REST APIs or issuing Mason CLI commands.
All users can create API keys, however, they can only assign scopes equal to or lower than their user scopes. For example, if a user has a scope of fleet:manager, they will only be able to create an API key with fleet:manager, fleet:read, or fleet:deploy – you cannot assign fleet:admin to the API key because that also include the notify scopes, which fleet:manager does not have permissions to manage
For more information on creating API keys, see https://docs.bymason.com/how-to/api.
Definitions of scopes
Account
Note: Only available with User scopes.
Description: Scopes within the account section provide access account-wide.
| Type: | Scope: | Action: |
| Account | Owner | Grants full administrator access to all resources and fleet actions. |
Fleet
Description: Scopes within the fleet section provide access to devices, groups, and projects.
| Type: | Scope: | Action: |
| Fleet | Admin | Grants a user or API key full administrator access to projects and inherits device and group admin scopes from fleet:manager. |
| Fleet | Manager |
Grants a user or API key full administrator access to device and group actions such as:
|
| Fleet | Read | Grants a user or API key read-only access to all projects, devices and groups. |
| Fleet | Deploy | Grants a user or API key the ability to issue deployments to existing deployable objects (project, APKs, or OS) to all groups. Suggestion: Pair this scope with fleet:read to ensure the user or API key can access the group identifiers and assets required to create the deployment.
Note: This scope alone will not allow you to upload artifacts (APKs, boot animations, or splash images) or create new project builds, fleet:manager + registry:admin is required to create these new assets. |
| Fleet | Move |
Grants user or API key to move any device(s) between all groups. Suggestion: Pair this scope with fleet:read to ensure the user or API key can access the device and group lists required to initiate the device move. |
| Fleet | Locate | Grants user or API key the ability to see device location information. |
| Type: | Scope: | Action: |
| Notify | All | Grants user or API key complete control of remote device actions. |
| Notify | Refresh | Grants user or API key the ability to send a request to a remote device for a new heartbeat. |
| Notify | Check | Grants user or API key the ability to send a request to a remote device to check for updates. |
| Notify | Reboot | Grants user or API key the ability to send a request to a remote device to reboot. |
| Notify | Shutdown | Grants user or API key the ability to send a request to a remote devices to shutdown. |
| Notify | Wipe |
Grants user or API key the ability to send a request to a remote device to perform a wipe.
Note: A wipe command will perform a factory reset on the device while preserving any deployments installed on the device. For example, if a device is running a deployment of Project A, then any OS configurations, APKs, boot animation, or splash images installed by Project A will persist the wipe command. |
| Notify | Application |
Grants user or API key the ability to send a custom notification (broadcast) to a user application running on a remote device. For more information about customer notifications, see https://docs.bymason.com/how-to/broadcast-api-guide |
| Notify | Refurbish |
Grants user or API key the ability to send a request to a remote device to perform a refurbish command. For more information about refurbishing devices, see https://docs.bymason.com/how-to/refresh-devices#how-to-refurbish-a-device
Note: A refurbish command will delete all device data from the Mason platform and device and unregister it from your account. |
Xray
Description: Scopes within the xray section provide remote control access to devices via xray. For more information about xray, see https://docs.bymason.com/how-to/xray.
| Type: | Scope: | Action: |
| Xray | Admin | Grants a user or API key the ability to establish an Xray remote session with any device in the account. With this scope, the user or API key will have access to all xray actions. |
Users
Description: Scopes within the user section provide access to all other users within the account. This includes the ability to control account-level MFA. For more information about MFA, see Mason’s Secure Login for Controller
| Type: | Scope: | Action: |
| User | Admin |
Grants a user administrator control over all other users within the account which includes the ability to modify any user’s scopes. |
| User | Read |
Grants read-only access to view all users within the account. |
Registry
Description: Scopes within the fleet section provide access to devices, groups, and project resources.
| Type: | Scope: | Action: |
| Registry | Admin |
Grants a user administrator control of all artifacts registered in the account, including the ability to create new project builds and upload APKs, boot animations, and splash images. |
| Registry | Read |
Grants read-only access to view all artifacts registered in an account. |
Connectivity
Description: Scopes within the connect section provide access to data usage, usage notifications, and SIM control actions.
| Type: | Scope: | Action: |
| Connect | Admin |
Grants a user administrator control of all SIMs in the account, including the ability to enable or disable SIMs, generate data usage rules for notifications, and view data usage. |
| Connect | Read | Grants read-only access to view SIM data usage, SIM states, and data usage notifications. |
Required Scope(s) for Common Actions
Note: the scope(s) listed for each action below are the minimum scopes required.
Actions: |
Type: | Scope: |
Creating a Project build in Controller via build wizard (Build and Deploy) |
User | fleet:manager + registry:admin |
Creating a Project via CLI (mason create project) |
API Key | fleet:manager |
Registering a project via CLI (mason register config) |
API Key | registry:admin |
Deploy existing Projects, APK, or OS from Controller |
User | fleet:deploy |
Deploy existing Project, APK, or OS from CLI (e.g. mason deploy config) |
API Key | fleet:deploy |
View devices and device detail pages in Controller |
User | fleet:read |
View groups and group detail pages in Controller |
User | fleet:read |
View projects and project details pages in Controller |
User | fleet:read |
Enabling or disabling SIM from Controller |
User | connect:admin |
Create SIM Notifications in Controller |
User | connect:admin |
View Connectivity data usage on the SIMs page in Controller |
User | connect:read |
Initiate X-ray connection from Controller |
User | xray:admin |
Initiate X-ray connection from CLI (e.g. mason xray logcat) |
API Key | xray:admin |
Move devices between groups from Controller |
User | fleet:move |
Move devices between groups from APIs (v1/default/group/{group_name}/move) |
API Key | fleet:move |
Register APK, boot animation, or splash image in Controller |
User | registry:admin |
| Register APK, boot animation, or splash image in CLI
|
API Key | registry:admin |
View projects & assets (artifacts) in Controller |
API Key | registry:admin |
Get projects from CLI (e.g. mason get project) |
API Key | fleet:read AND registry:read |
Create a new user in Controller |
User | fleet:read |
Update a user scope set in Controller |
User | user:admin |
View all users and their scopes in Controller |
User | user:admin |
Send reboot command to a device in Controller |
User | user:read |
Send a reboot command to a device via API (v1/default/device/reboot) |
API Key | notify:reboot** **If you don’t have the device ID for the target device(s), you will also need fleet:read to get the device identifier. |