The Samsara web API enables access to all of your data in the Samsara Cloud using an HTTPS-based RPC-style API. Use the API to access:
Real-time and historical data for any time period and sample frequency can be requested
Temperature, Humidity, Power and Input Module data available
Access to the API is enabled for all customers
Authentication security is provided by an API Token and Secret Key system
Data delivered securely in JSON format over TLS
API versions are released periodically.
For detailed information on the Samsara API, see the developers portal at developers.samsara.com.
You can manage API Tokens for secure access to the API on the API Tokens settings page. For detailed information on API tokens, see the Authentication Guide.
To create an API token, you must be assigned a Full Admin or Standard Admin role or a Custom Roles with the following permissions.
Edit permissions to see and edit API Tokens
Edit permissions to create, edit, and delete users, roles, tags
In both cases, your role must have access to manage the Entire Organization. Roles that use Tags for reduced scope (also known as Tag-Level Admins) are not sufficient.
You can request and delete as many API Tokens as required.
To set up an API token:
Select the Settings icon (
) at the bottom of your Samsara dashboard to view dashboard settings.
-
Select API Tokens.
Click + Add an API Token.
-
Define the token properties:
Enter a descriptive Name for your API token that describes the primary purpose.
Select the level of Tag Access for your token. For more on tags, see Tags.
-
Select a Permission Scope for your API token:
Save your changes.
-
After you create the token, copy it as shown below. The token will become unreadable after the page is refreshed, so be sure to record the token string in a secure location.
If you forget to copy or lose an API token, you can generate a new token string.
Note
If there is an integration actively using an API token, it will break when you regenerate this API token. This is because the previous key will be deleted and replaced with a new key. Take the appropriate caution before confirming.
You can upgrade the API token version in your admin console. Samsara only increments the API version when there is a breaking change to the API.
Examples of breaking changes include:
Adding a mandatory request parameter to existing API methods
Removing properties from existing API responses
For non-breaking changes, these will be accessible across all versions of the API.
Examples of non-breaking changes include:
Adding new API resources
Adding new optional request parameters to existing API methods
Adding new properties to existing API responses
Changing the order of properties in existing API responses
Changing the length or format of object IDs or other opaque strings
You can find the version on the API Tokens page in the dashboard:
Upgrading your API version will affect the API calls you make without a Samsara-Version header: the parameters you can send and the structure of objects returned.
You can test a newer version for an API call by setting the Samsara-Version header. In the example code below, a user with the <2018-01-01 token> could make a one-off request for the 2019-02-22 version by passing an X-Samsara-Version HTTP header with the desired datestamp version:
GET -H "X-Samsara-Version: 2019-02-22" https://api.samsara.com/v1/fleet/list?access_token=<2018-01-01 token>
After you are confident your code can handle the latest version, click Upgrade in your Samsara dashboard. This switches the version used by API calls with no Samsara-Version header.
