API Authentication

Generate an API token for your application


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:

    "name": "Driver in West Tag",
    "username": "driverInWestTag",
    "password": "driverInWestTagPassword",
    "tagIds": [

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
API EndpointRequired 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
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
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 (*requires Write ELD Hours of Service (US) scope too)
GET v1/fleet/drivers/summary (*requires Read ELD Hours of Service (US) scope too)
GET v1/fleet/maintenance/dvirs
POST v1/fleet/maintenance/dvirs
GET v1/fleet/maintenance/list
POST v1/fleet/maintenance/list
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
POST v1/fleet/drivers/summary
GET v1/fleet/drivers/summary
ELD Hours of Service (US)
GET v1/fleet/assets
POST v1/industrial/csv_imports
GET v1/industrial/data
GET v1/industrial/data/.dataInputId
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
GET v1/fleet/messages
POST v1/fleet/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
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
GET v1/tags
POST v1/tags
DELETE v1/tags/.tagId
GET v1/tags/.tagId
PATCH v1/tags/.tagId
PUT v1/tags/.tagId
GET v1/fleet/assets/reefers
GET v1/fleet/assets/.assetId/reefer
GET v1/user_roles
GET v1/users
POST v1/users
DELETE v1/users/.userId
GET v1/users/.userId
PATCH v1/users/.userId
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

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