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.

Jump to: Resource Owner | Authorization Code | 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.

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.

{
  "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.

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.

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.

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.

{
  "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.

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

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

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.

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"
}

{
  "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.

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.