Skip to main content

Authentication and Authorization

ShipperGuide TMS utilizes the OAuth2 Client Credentials flow to secure API access. Follow these steps to authenticate and authorize your API requests:

1. Obtain Your Client Credentials​

Before you can interact with the API, you need to obtain your Client ID and Client Secret. These credentials are unique to your account and are necessary for authentication.

  • Contact Your Account Representative: Reach out to your ShipperGuide account representative to request your credentials.
  • Need Help? Click here to get in touch with our support team if you don't have an account representative or need assistance.
warning

Client ID and Client Secret are the equivalent of the username and password of your application to access the API. Never share the client secret with anyone else and store it like you would store a password.

2. Obtain an Access Token​

Once you have your credentials, you can request an access token. Send a POST request to the /auth/token endpoint using Basic Authorization. The credentials are passed in the Authorization header in the form of Basic <base64_encoded_client_credentials>.

Encoding Your Credentials​

To encode your credentials, concatenate your client_id and client_secret with a colon (:) and then base64 encode the resulting string. For example:

client_id:client_secret

To encode this in base64, you can use the following command in bash:

echo -n "client_id:client_secret" | base64

This will produce a string like:

Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Note: Most major HTTP clients across various programming languages (such as Python's requests, JavaScript's axios, and others) have built-in support for handling Basic Authentication, making it easy to implement this encoding.

Request​

curl -X POST https://api.loadsmart.com/auth/token \
     -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials"
  • Authorization: This header should contain the word Basic followed by a space and the base64 encoded string.
  • Content-Type: Set to application/x-www-form-urlencoded.
  • grant_type: The type of grant you are using, in this case, client_credentials.

Response​

A successful response will include an access token. Here's a sample response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "expires_in": 7200
}
  • access_token: This token is used to authenticate your API requests.
  • token_type: Typically, this will be Bearer.
  • expires_in: The token's validity period in seconds (7200 seconds = 2 hours).

3. Use the Access Token​

With the access token, you can authenticate your API requests. Include the token in the Authorization header:

Example Request​

curl -X GET https://api.loadsmart.com/api/v3/YOUR_ENDPOINT \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with the access token you received, and YOUR_ENDPOINT with the specific API endpoint you wish to access.

Example: Creating a new Shipment​

To create a new shipment, your request might look like this:

curl --request POST \
  --url https://api.loadsmart.com/api/v3/shipments/ \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "shipper_uuid": "5c5d1123-948c-4327-bfcc-08536f5f1064",
  "equipment_type": "DRV",
  "mode": "FTL",
  "shipment_reference": "REF987654321",
  "stops": [
    {
      "address": "123 Main St",
      "city": "Springfield",
      "zipcode": "12345",
      "state": "IL",
      "country": "USA",
      "index": 0,
      "type": "pickup",
      "planned_date": "2024-01-01"
    },
    {
      "address": "456 Elm St",
      "city": "Shelbyville",
      "zipcode": "67890",
      "state": "IL",
      "country": "USA",
      "index": 1,
      "type": "delivery"
    }
  ]
}'

4. Token Expiry and Renewal​

Remember that the access token is valid for 2 hours. After it expires, you will need to request a new token using the same process described above.

Ensure that your application can handle token renewal seamlessly to maintain uninterrupted access to the API.

By following these steps, you can securely interact with the ShipperGuide API using OAuth2 authentication. If you encounter any issues, please refer to our API documentation or contact our support team.