API Basics

The Samsara Web API enables access to all of your data in the Samsara Cloud using 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

Create an API Token

You can manage API Tokens for secure access to the API on the Settings ( ) > API Tokens page. Detailed information on API tokens can be found in the Authentication Guide.

To create an API token, you must have Write Admin permissions to see and edit API Tokens and access to the Entire Organization access (access using Tags is insufficient). Read-Only Admins do not have access to view or create API Tokens on the Samsara dashboard. 

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. Provide 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 knowledge base.
• 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. After you create the token, copy it as shown below. The token will become unreadable once the page is refreshed, so be sure to record the token string in a secure location.

You can 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/.

Regenerating API Tokens

You can generate a new token string by clicking the ellipsis button and selecting Regenerate. Please be aware that If there is an integration actively using this API token, it may 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.

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.