OAuth 2.0 provides your app with a framework to request an API access token for a given Samsara customer automatically. This makes it easier for customers to install your integration with a click-through flow in a Samsara UI instead of requiring manual API token sharing, which is less secure.

To get started, navigate to the page called "OAuth 2.0 Apps" in "Settings" as shown below

Next, create a new App and set the following:

• Name of your app that you want to set - this will eventually be visible to Samsara dashboard users once your app/integration goes live.
• The redirect URL for your app
• Whether you want your app to be installed directly from the Samsara Dashboard. This is not required, and users can still install your app from your own portal. If you do, provide a Direct Install URL.
• What permissions you want your app to have. There are a number of different scopes that map to specific Samsara endpoints. You can see which scopes are required to access each endpoint on the endpoint's documentation on https://www.samsara.com/api. Once you select these, anyone who installs the app will see these scopes called out before they grant permissions to the app.

❗️

Warning: any changes to your scopes will be applied to ALL app installs

If you decide to add or remove scopes from your OAuth 2.0 app definition, keep in mind that all existing installs will also be impacted by these new scopes changes all at once.

Once configured, your will be given a unique Client ID and Client Secret tied to your app, which will be used in the OAuth flow. The Client Secret should be kept private.

The OAuth 2.0 Protocol

Samsara follows the standard OAuth 2.0 authorization code grant flow.

Step 1: Redirect users to Samsara to grant access

In order for Samsara organizations to grant you access to their data, your app should redirect them to the following URl:

https://api.samsara.com/oauth2/authorize

You should provide the following query parameters as part of the URL:

• client_id - required - issued to you by the Samsara team when you register your app.
• redirect_uri - optional - This is the URI of your application that we will redirect users back to after they've granted access. You can provide multiple redirect URIs when you register your app, and this parameter is only required if you have multiple. All redirect URIs must use the SSL protocol (https).
• state - required - This should be a code that you generate to prevent CSRF attacks. You can verify this code when the user is redirected back to your application to make sure that the request is coming from the same user that initiated the flow. This parameter is similar to a cookie. It should be unique each time you initiate the flow. It must be more than 8 characters.
• response_type - required - must be "code" as we only support the authorization code grant flow currently.

Example

Your app could display a button that says: "Connect to Samsara" with the following link:

https://api.samsara.com/oauth2/authorize?client_id=IEC65XwwV9&state=z3qAr0h5Ud&response_type=code

Step 2: Users are redirected to your app with an authorization code

Upon granting access, users are redirected back to your app's redirect_uri with the following query parameters:

• code - authorization code you will use to request an API access token. Expires after 10 minutes.
• state - this should be the same as the state parameter you provided in Step 1. If it is different, then this request may have been initiated by an attacker, and the flow should be aborted.
• scope - this will be the access-level scope that your app was configured for. Currently, this will either be admin:read for read-only apps or admin:write for full-access read/write apps.

If a user denies access to your application, the following query parameters will be provided when the user is redirected back to your redirect_uri:

• error will be scope_not_granted

The error parameter will contain other helpful error messages if another type of error occurs.

Example

A successful redirect back to your app might look like:

https://my-app.com?code=hgg2tziN39&state=z3qAr0h5Ud&scope=admin%3Aread

If the authorization was not granted, the redirect would look like:

https://my-app.com?error=scope_not_granted

Step 3: Exchange authorization code for API access token

If you have successfully received an authorization code, you can exchange it for an API access token using the following method:

POST https://api.samsara.com/oauth2/token

Authorization

• HTTP Basic: Base64 encode your client_id and client_secret as part of the HTTP Authorization header. Example: Authorization: Basic bXlfaWQ6bXlfc2VjcmV0. The code after "Basic" is the base64 encoded string "my_id:my_secret".

Body

• Content-Type: application/x-www-form-urlencoded
• Arguments:
  • code - required - the verification code provided to you in Step 2.
  • grant_type - required - must be authorization_code.

Response

You'll receive a JSON response containing the following:

{
    "access_token": "hXdwQUq3GBKZTvSLyURh",
    "expires_in": 3599,
    "scope": "admin:read",
    "token_type": "bearer",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

• access_token is will be the token you use to authenticate with the Samsara API.
• expires_in will be the number of seconds before the access token expires. Access tokens expire after 1 hour. After the access token expires, you must request a new one using the refresh token. See Refresh Tokens.
• scope will either be admin:read for read-only apps or admin:write for full-access read/write apps.
• token_type indicates that the access token is to be used with the Authorization: Bearer HTTP header in calls to the Samsara API.
• refresh_token is the token you will use to request a new access token when your access token expires. See Refresh Tokens.

📘

Once a verification code has successfully been exchanged for a token, the code will no longer be valid.

Example

Here's how you might exchange a verification code for an access token:

POST /oauth2/token HTTP/1.1
Host: api.samsara.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic bXlfaWQ6bXlfc2VjcmV0

code=hgg2tziN39&grant_type=authorization_code

curl -X POST \
  https://api.samsara.com/oauth2/token \
  -H 'Authorization: Basic bXlfaWQ6bXlfc2VjcmV0' \
  -d 'code=hgg2tziN39&grant_type=authorization_code'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.samsara.com/oauth2/token",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic bXlfaWQ6bXlfc2VjcmV0",
  },
  "data": {
    "code": "hgg2tziN39",
    "grant_type": "authorization_code"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

import requests
import base64

url = "https://api.samsara.com/oauth2/token"
credentials = "my_id:my_secret"
encoded_credentials = str(base64.b64encode(credentials.encode('utf-8')), 'utf-8')

payload = "code=hgg2tziN39&grant_type=authorization_code"
headers = {
    'Content-Type': "application/x-www-form-urlencoded",
    'Authorization': "Basic " + encoded_credentials
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.json())

Step 4: Make API calls with access token

You authenticate to the API by providing your access token to the Authorization: Bearer HTTP header:

Authorization: Bearer hXdwQUq3GBKZTvSLyURh

The API access token can be used with all our APIs as long as the API accesses the appropriate scope of your token: full-access read/write (scope = admin:write) or read-only (scope = admin:read).

The token will expire according to the expires_in value you received when requesting the access token in Step 3. Access tokens expire after 1 hour. To request a new one see Refresh Tokens.

Step 5: Refresh Tokens

After an access token expires, you must request a new one using the refresh_token provided in Step 3. You can use the following method:

POST https://api.samsara.com/oauth2/token

🚧

Warning against concurrent OAuth refresh requests

Do not make concurrent requests to the /oauth2/token endpoint to refresh the same API token.

You must only make one request at a time with the same refresh token, otherwise your integration may break. Wait until receiving a response code from Samsara before retry (calling the endpoint again).

• refresh tokens may only be used once, then they expire
• we recommend conservative retry logic: you should receive a response from Samsara in milliseconds, however the upper bound (p99) can be up to 20 seconds due to server load and processing times

Note that you may make concurrent requests to the other Samsara endpoints using the same access token (e.g. to /fleet/drivers or /fleet/vehicles, etc.).

Authorization

• HTTP Basic: Base64 encode your client_id and client_secret as part of the HTTP Authorization header. Example: Authorization: Basic bXlfaWQ6bXlfc2VjcmV0. The code after "Basic" is the base64 encoded string "my_id:my_secret".

Body

• Content-Type: application/x-www-form-urlencoded
• Arguments:
  • refresh_token - required - the refresh token provided to you in Step 3.
  • grant_type - required - must be refresh_token.

Response

You'll receive a JSON response containing the following:

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "expires_in": 3599,
    "scope": "admin:read",
    "token_type": "bearer",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

• access_token will be the new access token you use to authenticate with the Samsara API.
• expires_in will be the number of seconds before the new access token expires. After the access token expires, you must request a new one using the refresh token.
• scope will either be admin:read for read-only apps or admin:write for full-access read/write apps.
• token_type indicates that the access token is to be used with the Authorization: Bearer HTTP header in calls to the Samsara API.
• refresh_token is the new refresh token to use for the next time the access token expires.

🚧

Once you've used a refresh token, it cannot be used again. Make sure to update both your access token and your refresh token each time you refresh.

Direct Install from Samsara Dashboard

Your application will kick-off the OAuth 2.0 flow starting in Step 1. Users can initiate this flow directly from your application, or we can link them to your application in the Samsara dashboard.

When registering your app, you can provide us with a "Direct Install URL". This should be a link to your application where the user can then initiate Step 1 of the OAuth flow.

Revoking Access

Users may revoke authorization from your app via the Samsara Apps page in the Samsara dashboard. If they do so, the OAuth2 API and refresh tokens for that organization will become invalid and will trigger a 400 error code with the following message: "The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."

You may also enable users to revoke authorization from your app by calling the following API when a user indicates that they'd like to revoke access:

POST https://api.samsara.com/oauth2/revoke

Authorization

• HTTP Basic: Base64 encode your client_id and client_secret as part of the HTTP Authorization header. Example: Authorization: Basic bXlfaWQ6bXlfc2VjcmV0. The code after "Basic" is the base64 encoded string "my_id:my_secret".

Body

• Content-Type: application/x-www-form-urlencoded
• Arguments:
  • token - required - this should be the active refresh token for the organization requesting revocal of app authorization. The associated API access token will also be revoked along with this refresh token.

Response

You'll receive a 200 HTTP response code if the response is successful.

Publishing your Oauth 2.0 App to the Samsara App Marketplace

Once you feel confident you have completed the main code of your integration and have tested with one or more customer, complete the requirements to be considered for Samsara App Marketplace certification.