> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Samsara OAuth Configuration

> Here's a step-by-step guide to configure an OAuth2 client for Samsara

## Overview

This guide provides detailed instructions on integrating Samsara with your Terminal instance.

This is required for Samsara specifically in order to guarantee:

* The OAuth flow is consistent with your branding.
* The permissions are customized for your specific needs.
* You can publish your application in the Samsara [marketplace](https://www.samsara.com/resources/marketplace/).

<Note>
  Samsara operates different portals for different regions. Terminal supports
  North America ([cloud.samsara.com](https://cloud.samsara.com)) and Europe
  ([cloud.eu.samsara.com](https://cloud.eu.samsara.com)). If you have customers
  in both regions, you will need to complete the steps below for each region.
  Make sure to use a unique email address for each region because the same email
  cannot be used for multiple regions.
</Note>

## Creating a Developer Account

<Note>
  You can skip this step if you already have a Samsara developer account in the
  relevant region
</Note>

<div
  style={{
position: 'relative',
paddingBottom: '64.90384615384616%',
height: '0',
}}
>
  <iframe
    src="https://www.loom.com/embed/366eb52d7b7f48578a7ad63564fd9df7?sid=2df5e971-309a-40c8-8391-6cd4acb85243"
    frameborder="0"
    webkitallowfullscreen
    mozallowfullscreen
    allowfullscreen
    style={{
  position: 'absolute',
  top: '0',
  left: '0',
  width: '100%',
  height: '100%',
}}
  />
</div>

1. Submit Samsara's [partner application form](https://developers.samsara.com/docs/application-process).
2. Accept the invite Samsara sends you to create a developer account. This may take up to 7 business days.
   * If you don't receive an invite after 7 business days, reach out to `support@withterminal.com`.
3. Invite `support@withterminal.com` to your Samsara organization.

## Creating an OAuth Application

<div
  style={{
position: 'relative',
paddingBottom: '64.90384615384616%',
height: '0',
}}
>
  <iframe
    src="https://www.loom.com/embed/b1bd0b73a0cd461099522489dc1ea793?sid=35d65baf-1b4c-42a4-9a2f-7c4285124dc1"
    frameborder="0"
    webkitallowfullscreen
    mozallowfullscreen
    allowfullscreen
    style={{
  position: 'absolute',
  top: '0',
  left: '0',
  width: '100%',
  height: '100%',
}}
  />
</div>

<Note>
  If you support multiple regions, repeat these steps in each regional portal
</Note>

To create an OAuth application with Samsara, follow these steps:

1. **Create a new application**:
   * Log in to your Samsara dashboard ([North America Link](https://cloud.samsara.com/organizations/list) | [EU link](https://cloud.eu.samsara.com/organizations/list)) and go to the **Apps** tab
   * Click **Create new app**
   * Enter the required details (name, tag line, logo, etc.)

2. Under **Redirect URLs**, add:

```
https://link.withterminal.com/oauth/callback/samsara
```

3. Choose the necessary **Scopes** for your application.

<Accordion title="Which scopes should I choose?">
  Below is a summary of the scopes you might need from Samsara, depending on the Terminal common models you intend to utilize.

  <Tip>
    It's best to request all the permissions you might need upfront. Adding
    permissions later will require customers to re-authenticate, which can be
    avoided with early planning.
  </Tip>

  | Common Model                                         | Samsara Scope                                                                                                                                |
  | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  | **General** (required)                               | `Setup & Administration > Read Org Information`<br />`Setup & Administration > Read Webhooks`<br />`Setup & Administration > Write Webhooks` |
  | **Vehicles** (required)                              | `Vehicles > Read Vehicles`                                                                                                                   |
  | Groups                                               | `Setup & Administration > Read Tags`                                                                                                         |
  | Devices                                              | `Setup & Administration > Read Gateways`                                                                                                     |
  | Drivers                                              | `Drivers > Read Drivers`                                                                                                                     |
  | Vehicle Locations<br />Vehicle Stat Logs             | `Vehicles > Read Vehicle Statistics`<br />`Assignments > Read Assignments`                                                                   |
  | Trips                                                | `Vehicles > Read Vehicle Trips`                                                                                                              |
  | Trailers                                             | `Trailers > Read Trailers`<br />`Equipment > Read Equipment`                                                                                 |
  | Trailer Locations                                    | `Trailers > Read Trailer Statistics`<br />`Equipment > Read Equipment Statistics`                                                            |
  | HOS Logs<br />HOS Daily Logs<br />HOS Available Time | `Compliance > Read ELD Hours of Service`<br />`Compliance > Read ELD Compliance Settings`                                                    |
  | Safety Events                                        | `Safety & Cameras > Read Safety Events & Scores`<br />`Safety & Cameras > Read Camera Media` (optional)                                      |
  | IFTA Summaries                                       | `Compliance > Read IFTA (US)`                                                                                                                |
  | Passthrough                                          | *Select any other scopes you plan to leverage if using [passthrough](/terminal-platform/passthrough)*                                        |
</Accordion>

4. Click **Save** to create your application.
5. Click on the application you just created.
6. In the top right, change the app state to `Beta`. Learn more about app states [here](https://developers.samsara.com/docs/marketplace-apps#app-states).
7. Click **Save** to make your application available for customer use.
8. Invite `support@withterminal.com` to your Samsara organization.

## Update Samsara Configuration in the Terminal Dashboard

<Note>
  You will need your Production Terminal app provisioned before you can
  complete this step. If necessary, return here when that occurs.

  You must be a Terminal Dashboard admin to perform this step.
</Note>

1. Go to the Terminal Dashboard [Settings](https://dashboard.withterminal.com/settings?tab=application)
2. Scroll down to **Samsara**
3. Paste the **Client ID** and **Client Secret** from Samsara into the Terminal dashboard.
   * If you created applications in multiple regions, paste the credentials for each region under its respective section
4. Click **Save Changes** to save the configuration.
5. Begin connecting Samsara fleets to Terminal 🚛

## Connecting Samsara Fleets

<Warning>
  The user authorizing the connection on the fleet's Samsara account must have a
  **Full Admin** or **Standard Admin** role. Samsara blocks OAuth installs for
  users without one of these roles, and the error is surfaced on Samsara's side
  before the flow returns to Terminal.
</Warning>

## Publishing Your Application

Once your integration is in production and at least one Samsara fleet has connected to your application, follow Samsara's [App Certification Process](https://developers.samsara.com/docs/app-certification-process) to submit it for inclusion in the [Samsara App Marketplace](https://www.samsara.com/resources/marketplace/).

<Warning>
  Until your app is certified, fleets will see a banner during OAuth that says:
  "This application has not been formally certified by Samsara." This will not
  affect anyone's ability to connect through Samsara and it's okay for your app
  to remain in this state indefinitely.
</Warning>

<Note>
  If you support multiple regions, complete certification separately in each
  regional portal ([North America](https://cloud.samsara.com) and
  [Europe](https://cloud.eu.samsara.com)).
</Note>