API Basics

The Samsara Web API allows access to all of your data in the Samsara Cloud via an HTTPS-based RPC-style API.  Detailed information can be found in the API Guide here: developers.samsara.com

Key points:

• Realtime 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

Creating API Tokens

API Tokens for secure access to the API can be viewed and created on the API Tokens Settings page. Detailed information on API tokens can be found in the Authentication Guide. Below are instructions on how to set up an API token:

1. On your Samsara Dashboard, navigate to Settings  > API Tokens. 

2. Click + Add an API Token to create a new token.  

• Select a Name for your API token. We recommend creating a new API token with a descriptive name for each application you create.
• Select the level of Tag Access for your token.
  • For more on tags, view this guide on our knowledgebase.
• Select a Permission Scope for your API token:
  • For more on how to set Scopes for API tokens, view this guide on our developer site
  • For more on how to create API tokens for 3rd Party Integrations correctly, view this guide on our developer site.

3. Select Save once you've inputted a Name and Permission Scope. 

4. Once your create the token, you can copy it as shown below. The token will become unreadable once the page is refreshed, so be sure to save the token string in a secure location.

You may request and delete as many API Tokens as required. 

API versions are released periodically and more information on versioning can be discovered at https://developers.samsara.com/.

Please note that Read-Only Admins do not have access to view or create API Tokens on the Samsara Dashboard. 

Upgrading API Tokens

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

How to upgrade your API version

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>

Once you are confident your code can handle the latest version, click on the "Upgrade" button in your Dashboard. This switches the version used by API calls with no Samsara-Version header.