📘

All API requests to Samsara must do the following in order for request to be successfully sent:

• use https (not http). Read this for more on https
• use TLS protocol version 1.2 or above

To make a call to the Samsara REST API, you need an API token. There are two types of API authentication mechanisms that will provision an API token for you:

• (1) Bearer API Tokens
• (2) OAuth 2.0

NOTE: Your API tokens carry many privileges, so be sure to keep them secure. Do not share your secret API tokens in publicly accessible areas such as GitHub, client-side code, and so on.

NOTE: CORS (Cross Origin Resource Sharing) is not currently supported by Samsara. This means that all REST API requests to Samsara should be made from a server-side application and cannot be made from front-end applications running in a browser.

Bearer API Tokens

Samsara uses the Bearer Token HTTP authentication scheme for API tokens. In order to use the authentication token, include it in the Authorization header in your HTTP request:

curl --request GET 'https://api.samsara.com/fleet/vehicles' \
--header 'Authorization: Bearer <<token>>'

Creating an API Token

📘

As of April 11th, 2022, Samsara made a user experience change to how API tokens are created to add additional security. The new user experience is described below and will be applied for all new API tokens created.

Note: all tokens created prior to April 11th, 2022 will still be visible in plaintext and not blurred out. Samsara will soon announce a backfill where previous tokens will be blurred out as well

Go to the Settings page of the Samsara Dashboard by clicking the gear icon on the left-side nav bar. Then scroll down to "API Tokens". Click "Add an API Token" to create a new API token as shown below:

When creating a token, you will need to set:

• API Token Name: the best practice is to have one API token for a single integration. If you have multiple API tokens, we recommend creating a unique API token per integration
• Tag Access: this limits which Samsara tags can be accessed when using the API token. See more below.
• Granular Scopes: this limits which types of data can be accessed when using the API token. See more below.

Once your create the token, you can copy it as shown below:

Once you create your API token, you will not be able to access the plaintext for the token after your copy it. Be sure to keep the token safe after copying. If you lose the token, you can regenerate the token as shown below.

NOTE: If you regenerate the token, the previous token will stop working, so be sure that no live integrations are heavily dependent on the existing token during the time you regenerate otherwise those integrations may break.

Tag Access

You can add tag scopes to your API token:

This will limit the scope of the API token to the tags that you select. (By default, an API token will be created with access to the entire organization). Data that is not within one of the selected tags will not be accessible to the API token.

🚧

In order to successfully create data using a Full Admin tag-scoped token, the given tag must be included in the request body. For example, in order to create a driver using the "West Tag Full Admin" API token above, the tag ID for the "West" tag must be included in the API request:

JSON

{
    "name": "Driver in West Tag",
    "username": "driverInWestTag",
    "password": "driverInWestTagPassword",
    "tagIds": [
        "2931064"
    ]
}

Granular Scopes

Granular scopes give you the ability to limit what API endpoint(s) the token can access to create, retrieve or manipulate data. You can set granular scopes when you create an API token.

Each granular scope grants access to a specific set of API endpoints, and sometimes just one endpoint. The ability to Read or Write data is always broken out into two different scopes. For example, when you grant scope access to "Read Assignments", this limits token access to only the GET /fleet/driver-vehicle-assignments API endpoint, and nothing else. However, because granular scopes are applied at the level of API endpoints, the API response may include related data to the nominal granular scope. For example, GET /vehicles requires "Read Vehicle" scope access, however the API response includes driver information for vehicles that have a static driver assignment. Always consult the API reference documentation to see data returned for any API endpoint.

To determine the granular scope required to call a specific API endpoint, refer the API reference documentation. Here is an example:

See the screenshot below that showcases selecting scopes when creating/editing a new API token:

All newly created API tokens will have a default set of "Read" scopes selected:

• AEMP
• Alert Contacts
• Assignments
• Attributes
• Carrier-Proposed Assignments
• Driver App Settings
• Drivers
• Equipment
• Equipment Statistics
• Gateways
• Jobs
• Org Information
• Sensors
• Tags
• Trailer Statistics
• Trailers
• Users
• Vehicle Statistics
• Vehicle Trips
• Vehicles
• Webhooks

Legacy API Endpoint Scopes

If you are using any of our Legacy API Endpoints, refer to the required scopes below that would be needed to call these endpoints

• GET endpoints require the "Read" permission for the relevant scope
• PUT, PATCH, POST, and DELETE endpoints require the "Write" permissions for the relevant scope
• NOTE: endpoints that are not publicly documented in our Legacy API Docs are not currently supported

OAuth 2.0 (Open Beta)

Check out the OAuth 2.0 page to see how you can enable users to automatically grant API access to your application.