Authentication

Generate an API token for your application

📘

OAuth 2.0 Beta

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

❗️

All API requests to Samsara must be sent using https (not http) and use TLS protocol version 1.2 or above in order for the requests to be successfully sent

To make a call to the Samsara REST API, you need an API token. 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:

Samsara uses the Bearer Token HTTP authentication scheme. 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>>'

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.

The API uses HTTPS. Calls made over plain HTTP or without authentication will fail.

Scopes for API Tokens

You can scope an API token to limit what data and actions the API token has access to. If you are NOT part of the Beta for the Granular Scopes feature, you will have the ability to to give:

  • Full Admin access -- this allows the token to access all endpoints
  • Read-only Admin access -- this allows the token to access only endpoints that retrieve data (i.e. only GET endpoints)

[Closed Beta] Granular Scopes

If you are part of the Beta for the Granular Scopes feature, you can select a number of more granular scopes that further limit what data a token can create, retrieve, or manipulate. For example, you can elect to only give access to the token to read HOS Logs data, and nothing else. See an example below:

Applying a Read-only Admin or Full Admin scope for Granular Scopes

If you need to provide Read All access and/or Write All access for the purpose of creating an API token for a partner integration, you can do this by selecting all the "Read" permissions for all Scopes and or all the "Write" permissions for all Scopes.

Converting an existing API token to use Granular Scopes

If you click "Edit", you can scroll to the bottom and check the "Convert to Granular Scopes" checkbox and then press "Save". If you click to edit the token again, you will see that it now has the options to more granular scope the token.

Tag Access for API Tokens

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:

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

What’s Next
Did this page help you?