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