---
updatedAt: 2026-08-04T09:40:52.000Z
agentTools:
  projectIndex: https://developer.truckstop.com/llms.txt
---

# Token-based Authentication

Truckstop's REST APIs use token-based authentication. There are two ways to get a token: use **Resource Owner** if you are a proprietary system that holds the user's Truckstop credentials, or **Authorization Code** if you are a third-party TMS whose users sign in on Truckstop. Both produce the same token set, which you then use the same way.

<Callout icon="📘" theme="info">
  ### Token lifetimes

  An access token is valid for \~20 minutes with unlimited calls across every Truckstop API. A refresh token is valid for 6 months or a single use. Store both, reuse the access token, and refresh before it expires.
</Callout>

**Jump to:** [Resource Owner](#1-get-a-token-resource-owner)  |  [Authorization Code](#2-get-a-token-authorization-code)  |  [Use your token](#3-use-your-token)

# 1. Get a token: Resource Owner

For proprietary systems whose app already holds the user's Truckstop username and password.

**Step 1 - Request tokens** (your app to the auth server)

Send the username and password to `/auth/token` with a Basic auth header. This is the Resource Owner Password grant.

```http
POST /auth/token?scope=truckstop
Authorization: Basic MTIzOkFCQwo=          # base64 of "clientID:clientSecret"
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=jdoe&password=******
```

**Step 2 - Receive tokens** (the auth server to your app)

You get an access token, a refresh token, and the `claims` for the products the user is licensed for. Store both tokens, then continue to [Use your token](#3-use-your-token).

```json
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 1199,
  "refresh_token": "9f8a3c...",
  "claims": "[{...licensed products...}]"
}
```

# 2. Get a token: Authorization Code

For third-party TMS platforms. The user signs in on Truckstop's own page, and your client secret stays server-side.

**Step 1 - Redirect the user to sign in** (your app to the user's browser to Truckstop)

Authentication starts in the user's browser, not with a server call. Send the browser to Truckstop's authorize URL, as a link or an HTTP redirect. Truckstop shows its own sign-in page.

```text
https://api-int.truckstop.com/auth/authorize
  ?scope=truckstop
  &clientID=1154-55412-87551-412185
  &redirect_uri=https://yourapp/callback
  &response_type=code
```

**Step 2 - User signs in, code returned** (Truckstop to the user's browser to your redirect URI)

The user enters their own Truckstop credentials and approves access. Truckstop redirects the browser back to your redirect URI with a one-time authorization code. Your app never sees the user's password.

```text
302 Redirect
https://yourapp/callback?code=9f7144e3...
```

**Step 3 - Exchange the code** (your app to the auth server, server-to-server)

Exchange the code plus the same redirect URI for tokens, using the Basic auth header. This call happens server-side, so your client secret stays private.

```http
POST /auth/token?scope=truckstop
Authorization: Basic MTIzOkFCQwo=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=9f7144e3...&redirect_uri=https://yourapp/callback
```

**Step 4 - Receive tokens** (the auth server to your app)

Same token set as the other method. Store both tokens, then continue to [Use your token](#3-use-your-token).

```json
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 1199,
  "refresh_token": "9f8a3c...",
  "claims": "[{...licensed products...}]"
}
```

# 3. Use your token

Once you have an access token, the two methods converge. Send the token as a `Bearer` credential on every call, and reuse it for \~20 minutes.

**Example A - Post a load** (Load Management)

Every load needs at least two stops plus equipment and rate details. A success returns `201 Created`.

```http
POST /loadmanagement/v2/load
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{
  "loadStops": [ { "...pickup..." }, { "...delivery..." } ],
  "equipmentAttributes": { },
  "rateAttributes": { },
  "LoadActionAttributes": { "Type": 4 }
}
```

```json
201 Created
```

**Example B - Get a rate estimate** (Rate Insights)

The same token works here. Ask Rate Insights for a booked-rate estimate on a lane.

```http
POST /modeledrate/v3/booked/rateestimate
Authorization: Bearer eyJhbGci...
Content-Type: application/json

{
  "Origin": { "City": "Boston", "StateCode": "MA" },
  "Destination": { "City": "Boise", "StateCode": "ID" },
  "EquipmentCode": "V",
  "TransportationMode": "TL"
}
```

```json
{
  "predictedRate": 1615.42,
  "lowerRate": 1500.88,
  "upperRate": 1927.56,
  "ratePerMile": 3.70
}
```

**Keep going - Refresh before expiry** (your app to the auth server)

Before the access token expires, send your stored refresh token for a fresh pair. No credentials or sign-in needed again. Save the new tokens; the old pair stops working.

```http
POST /auth/token?scope=truckstop
Authorization: Basic MTIzOkFCQwo=
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=9f8a3c...
```

***

The **stage** (test) base URL is `api-int.truckstop.com`; production is `api.truckstop.com`. Requests use form-encoded bodies with an `Authorization: Basic` header (base64 of `clientID:clientSecret`). Payloads are abbreviated here; see each endpoint's reference page for the full schema.

<br />