All endpoints are hosted on https://api.bymason.com/v1.

All endpoints require authentication. Authentication is specified using API Keys. To use an API Key, set the Authorization header in your request to basic <api-key>. The full header should look as follows:

Authorization: basic <api-key>

To use an API Key against an endpoint, it needs to have the proper scope.

Every user and API key has an associated list of scopes. A scope enables a level of access to APIs for the request send by the user or API key. Each endpoint will validate the incoming request has the required scope before processing the request. The scope hierarchy is shown below with a description of each scope.

• account:owner: Full permissions for the account
  • fleet:admin: Grants administrator control over devices and groups
    • fleet:manager: Grants control over devices and groups
      • fleet:read: Grants read access on devices and groups
    • fleet:locate: Grants access to devices location data
    • notify:all: Grants send notifications for all notification types
      • notify:refresh: Grants send notifications to heartbeat
      • notify:check: Grants send notifications to check for updates
      • notify:reboot: Grants send notifications to reboot devices
      • notify:shutdown: Grants send notifications to shutdown devices
      • notify:wipe: Grants send notifications to wipe devices
      • notify:application: Grants send notifications to user-applications on devices
      • notify:refurbish: Grants send notifications to refurbish devices
  • xray:admin: Grants full use of Xray features
  • user:admin: Grants administrator control over users
    • user:read: Grants read access to users
  • registry:admin: Grants administrator control over the artifact registry
    • registry:read: Grants read access to the artifact registry
  • connect:admin: Grants administrator control over SIMs
    • connect:read: Grants read access to SIMs

Many of the platform APIs contain paginated results. All pagination follow a standard token-based pattern. Results are always stored in the data value as a list. If there is a next page, the token is stored in the nextPage value. If there is a previous page, the token is stored in the prevPage value.

To request the next or previous page, send a subsequent request with the next or previous token as the after or before query parameter.

Below is a sample JSON response from the paginated devices endpoint:

https://api.bymason.com/device
{
  "data": [{...}],
  "prevPage": "cHJldmlvdXMgcGFnaW5hdGlvbiB0b2tlbgo=",
  "nextPage": "bmV4dCBwYWdpbmF0aW9uIHRva2VuCg=="
}

Given the above response, you can query the next page by setting the after query parameter with the nextPage token:

https://api.bymason.com/device?after=bmV4dCBwYWdpbmF0aW9uIHRva2VuCg==
{
  "data": [{...}],
  "prevPage": "cHJldmlvdXMgcGFnaW5hdGlvbiB0b2tlbgo=",
  "nextPage": "bmV4dCBwYWdpbmF0aW9uIHRva2VuCg=="
}

The Mason API will return one of the following status codes for each request.

The Mason API uses a standard JSON body for all non-2XX status codes to represent errors. The body of the error response will follow the format:

{
  "type": "<error-type-category>",
  "context": "<error-message>"
}

An example error message for an Unauthorized error will look like:

{
  "type": "forbidden",
  "context": "The user does not have permission to take the desired action"
}

All timestamps used in the platform APIs are formatted using RFC3339, unless specified otherwise.

The Devices API endpoints enable you to monitor your fleet of devices.

The Actions API endpoints enable you to send commands to your fleet of devices. Each action is queued to the device. The device processes it's queue of actions when it is online and has an internet connection. If the device is online when the action is sent, it will process the action immediately.

The Project API endpoints enable you to view and manage your Mason projects. A Project is a collection of apps and configuration that can be deployed to a device.

The Deployment Groups API endpoints enable you to view and manage your groups of devices. A Deployment Group is a mechanism to deploy artifacts in bulk to devices. Each Group is locked to a specific Android API level and Mason device type. This allows you to move devices into a Deployment Group that should have the same Mason OS, Project, and Apps. Devices will auto-update their artifacts based on the Deployment Group they are in and the artifacts deployed to that group.

The Deployment API endpoints enable you to view and manage the artifacts deployed to your Deployment Groups. An artifact is either a Mason OS version, project build, or an app.

A Device is any Android based phone or tablet running Mason OS.

A Project is a collection of apps and configuration that can be deployed to a device.

A Deployment Group is a group of devices configured to run specific artifacts. Each Deployment Group has deployed artifacts which it propogates to every device that belongs in the group. An artifact is either a Mason OS version, project configuration, or an app.