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.
For more information, see the following resources on the Samsara Developers Portal:
-
To set scopes for API tokens, see API Authentication.
-
To create API tokens for third-party integrations, see 3rd Party Integration Tokens.
-
-
-
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.
Comments
0 comments
Please sign in to leave a comment.