Mason Platform APIs
The Mason Platform API is a series of REST routes that enable customers to perform operations against their fleet of devices using common internet standards of HTTP and OAuth.
Quick links
- Authorization Headers
- Pagination Parameters
- HTTP Status Codes
- Groups API
- Devices API
- Connectivity Usage API
- Connectivity SIM API
Authorization
All public Mason Platform APIs are authenticated, meaning you must supply an Authorization
header on every request.
The Authorization
header should include an API key with scopes that match the required scopes of the resource you are trying to access or update.
Visit our guide for creating an API key if you have not made one before
Sample request(s)
Pagination
Some of Mason's Platform API responses are paged by default, typically when we expect the resource that is being accessed to have many entries.
If a resource is paged, you can control the pagination logic using the following query parameters
Pagination Parameters
Name | Description | Example |
---|---|---|
limit | limits the number of items returned | ?limit=10 |
before | The key type will vary based on which API you're using | ?before=$BEFORE_KEY |
after | Begins a new page at the given after key. The key type will vary based on which API you're using | ?after=$AFTER_KEY |
limit
can be combined withbefore
andafter
params
When resources are paged, the following response attributes will be added to the response body you would normally see if the response is not paged.
Example Response (JSON)
{
...,
"prevPage": "BEFORE_KEY",
"nextPage": "AFTER_KEY"
}
Errors
The following explains how errors are formatted in Mason Platform APIs
Error JSON
For responses other than 200, the following format is expected:
{
"type": <error_type_category>,
"message": <error_message>
}
Example:
{
"type": "authentication_error",
"message": ""Required authorization token not found"
}
HTTP Status Codes
The Mason API will return the following status codes
Code | Description |
---|---|
200 - OK | Everything worked as expected. |
400 - Bad | Request,The request was unacceptable, often due to missing a required parameter. |
401 - Unauthorized | No valid API key provided. |
403 - Forbidden | The authorization token does not allow the requested action. |
404 - Not Found | The requested resource doesn't exist. |
409 - Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
500 - Internal Server Errors | Something went wrong on Mason's end. (These are rare.) |