Authentication

Generate an API token for your application

🚧

On 2/14/22, Samsara will begin converting in-use Legacy API Tokens to have Granular Scopes

To improve security for customers sharing data via API, we are going to slowly convert Legacy API Tokens (all tokens created prior to February 2022) to have granular scopes.

Read more in our changelog post here.

Note: this does NOT affect OAuth 2.0 apps

📘

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 (currently in Open Beta)

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 note 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:

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

Granular Scopes

All newly created API tokens will have Granular Scopes. 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.

In order to see which scopes are required to call an endpoint, refer to the endpoints documentation in our API Reference Docs. Here is an example:

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

Note that there will be a default set of "read" Scopes selected when creating a new API token:

  • 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

API Endpoint

Required Scope

GET v1/addresses
POST v1/addresses
DELETE v1/addresses/.address_id
GET v1/addresses/.address_id
PATCH v1/addresses/.address_id
POST v1/fleet/add_address

Addresses

GET v1/contacts
GET v1/contacts/.contact_id

Alert Contacts

GET v1/fleet/trailers/assignments
GET v1/fleet/trailers/.trailerId/assignments

GET v1/fleet/drivers/document_types
GET v1/fleet/drivers/documents
POST v1/fleet/drivers/.driver_id/documents
DELETE v1/fleet/drivers/.driver_id/documents/.document_id
GET v1/fleet/drivers/.driver_id/documents/.document_id

Documents

GET v1/fleet/drivers
POST v1/fleet/drivers
DELETE v1/fleet/drivers/create
GET v1/fleet/drivers/create
PATCH v1/fleet/drivers/create
POST v1/fleet/drivers/create
GET v1/fleet/drivers/inactive
GET v1/fleet/drivers/inactive/.driver_id
PUT v1/fleet/drivers/inactive/.driver_id
GET v1/fleet/drivers/inactive/.external_driver_id
PUT v1/fleet/drivers/inactive/.external_driver_id
DELETE v1/fleet/drivers/.driver_id
GET v1/fleet/drivers/.driver_id
PATCH v1/fleet/drivers/.driver_id
POST v1/fleet/drivers/.driver_id
DELETE v1/fleet/drivers/.external_driver_id
GET v1/fleet/drivers/.external_driver_id
PATCH v1/fleet/drivers/.external_driver_id
POST v1/fleet/drivers/.external_driver_id
POST v1/fleet/drivers/summary
GET v1/fleet/drivers/summary

Drivers

GET v1/fleet/maintenance/dvirs
POST v1/fleet/maintenance/dvirs
GET v1/fleet/maintenance/list
POST v1/fleet/maintenance/list

DVIRs

GET v1/fleet/drivers/.driver_id/hos/audit_logs
POST v1/fleet/drivers/.driver_id/hos/duty_status
GET v1/fleet/drivers/.driver_id/hos_certified_daily_logs
PATCH v1/fleet/drivers/.driver_id/hos_certified_daily_logs
GET v1/fleet/drivers/.driver_id/hos_daily_logs
PATCH v1/fleet/drivers/.driver_id/hos_daily_logs
POST v1/fleet/drivers/.driver_id/hos_daily_logs
GET v1/fleet/drivers/.driver_id/log_edits
GET v1/fleet/hos/audit_logs
GET v1/fleet/hos/log_edits
GET v1/fleet/hos_authentication_logs
POST v1/fleet/hos_authentication_logs
GET v1/fleet/hos_logs
POST v1/fleet/hos_logs
GET v1/fleet/hos_logs_summary
POST v1/fleet/hos_logs_summary
GET v1/fleet/unassigned_driving_logs
GET v1/fleet/unassigned_driving_segments
GET v1/fleet/unassigned_driving_segments/.segment_id
PATCH v1/fleet/unassigned_driving_segments/.segment_id
GET v1/fleet/vehicles/.vehicle_id/unassigned_driving_logs

ELD Hours of Service (US)

GET v1/fleet/assets
POST v1/industrial/csv_imports
GET v1/industrial/data
GET v1/industrial/data/.dataInputId

Equipment

GET v1/fleet/assets/locations
GET v1/fleet/assets/.assetId/locations

Equipment Statistics

GET v1/industrial/machines
GET v1/industrial/machines/.machineId
GET v1/industrial/machines/.machineId/form
POST v1/industrial/machines/.machineId/form
GET v1/industrial/machines/.machineId/forms
POST v1/industrial/machines/.machineId/forms
GET v1/industrial/mes/lines
GET v1/industrial/mes/recipes
GET v1/industrial/mes/runs
GET v1/industrial/mes/runs/line/.external_line_id
GET v1/industrial/mes/runs/line/.line_id
GET v1/industrial/mes/work_orders
POST v1/industrial/mes/work_orders
DELETE v1/industrial/mes/work_orders/.external_work_order_id
GET v1/industrial/mes/work_orders/.external_work_order_id
PATCH v1/industrial/mes/work_orders/.external_work_order_id
DELETE v1/industrial/mes/work_orders/.id
GET v1/industrial/mes/work_orders/.id
PATCH v1/industrial/mes/work_orders/.id
GET v1/industrial/vision/cameras
GET v1/industrial/vision/cameras/.cameraId/programs
GET v1/industrial/vision/run/camera/.cameraId
GET v1/industrial/vision/run/camera/.cameraId/program/.programId
GET v1/industrial/vision/runs
GET v1/industrial/vision/runs/.cameraId
GET v1/industrial/vision/runs/.cameraId/.programId/.startedAtMs
POST v1/machines/history
POST v1/machines/list

Industrial

GET v1/fleet/messages
POST v1/fleet/messages

Messages

GET v1/fleet/dispatch/routes
POST v1/fleet/dispatch/routes
GET v1/fleet/dispatch/routes/job_updates
DELETE v1/fleet/dispatch/routes/.route_external_id
GET v1/fleet/dispatch/routes/.route_external_id
PUT v1/fleet/dispatch/routes/.route_external_id
GET v1/fleet/dispatch/routes/.route_external_id/history
DELETE v1/fleet/dispatch/routes/.route_id
GET v1/fleet/dispatch/routes/.route_id
PUT v1/fleet/dispatch/routes/.route_id
GET v1/fleet/dispatch/routes/.route_id/history
GET v1/fleet/drivers/.driver_id/dispatch/routes
POST v1/fleet/drivers/.driver_id/dispatch/routes
GET v1/fleet/vehicles/.vehicle_id/dispatch/routes
POST v1/fleet/vehicles/.vehicle_id/dispatch/routes

Routes

GET v1/fleet/drivers/.driver_id/safety/score
GET v1/fleet/vehicles/.vehicle_id/safety/harsh_event
GET v1/fleet/vehicles/.vehicle_id/safety/score

Safety Events & Scores

GET v1/sensors/cargo
POST v1/sensors/cargo
GET v1/sensors/door
POST v1/sensors/door
POST v1/sensors/history
GET v1/sensors/humidity
POST v1/sensors/humidity
GET v1/sensors/list
POST v1/sensors/list
GET v1/sensors/temperature
POST v1/sensors/temperature

Sensors

GET v1/tags
POST v1/tags
DELETE v1/tags/.tagId
GET v1/tags/.tagId
PATCH v1/tags/.tagId
PUT v1/tags/.tagId

Tags

GET v1/fleet/assets/reefers
GET v1/fleet/assets/.assetId/reefer

Trailers

GET v1/user_roles
GET v1/users
POST v1/users
DELETE v1/users/.userId
GET v1/users/.userId
PATCH v1/users/.userId

Users

GET v1/fleet/locations
POST v1/fleet/locations
GET v1/fleet/vehicles/locations
GET v1/fleet/vehicles/stats
GET v1/fleet/vehicles/stats-expanded
GET v1/fleet/vehicles/.vehicle_id/locations

Vehicle Statistics

GET v1/fleet/trips
POST v1/fleet/trips

Vehicle Trips

GET v1/fleet/list
POST v1/fleet/list
POST v1/fleet/set_data
GET v1/fleet/vehicles/.external_vehicle_id
PATCH v1/fleet/vehicles/.external_vehicle_id
GET v1/fleet/vehicles/.vehicle_id
PATCH v1/fleet/vehicles/.vehicle_id

Vehicles

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.


What’s Next
Did this page help you?