How to connect to Loadsmart

Loadsmart uses JWT (JSON Web Tokens) as the authentication process for external partners. There are several libraries that can help you generate your JWT tokens.

As a basic guideline, you will need to:

  1. Generate a private/public key pair;

  2. Share with Loadsmart the public key;

  3. Store the issuer that Loadsmart will provide (uuid format);

To sign your JWT tokens you need some information. Each bit of information used to sign the JWT token is called a claim.

There are several claims that you need to provide while signing the token, in order for us to correctly authenticate you and properly authorize your requests.

The most important claims are:

  1. issuer. This is provider to you, by us and it’s an UUID.

  2. sub. This is represents which subject we are talking about. There are two basic types, sys and usr subjects.

In the API documentation you will see on the specific call you want to make if this expects a sys token, or a usr token.

What is the right sub?

This is practical example on how to determine the sub of a certain call.

Let’s imagine that you want to share a capacity with us. If you check there is several fields defined in the documentation. In order:

  1. Authorization

  2. Request Body Schema

  3. Payload Schema Definition

When you check the Authorization field, you will see that this endpoint requires a User-JWT authorization, so you need to use a usr subject.

Another example is the search carrier endpoint, that requires a Application-JWT authorization. This endpoint requires a sys subject.

In general, if the endpoint you want to use is talking about a carrier specific resource, such as an empty truck, a sourced load, a driver, etc, it probably requires a User-JWT token.

How to construct the correct sub?

For Application-JWT authorizations the construction of the sub is pretty simple. Just use a fixed value of sys and you are good to go.

For User-JWT authorizations, the construction of the sub is done by concatenating usr:, with the account uuid you will receive or will be returned in a call from one of our endpoints.

The template usr:<my-uuid> is a correct template. You can check the code sample below to see how the template is being used.

Generating the token

This is a simple example showing how to construct the payload, used to sign (generate) the token you will use to do the calls to Loadsmart’s API. This examples uses PyJWT

jwt.py
 1from datetime import datetime, timedelta
 2import os
 3import jwt
 4
 5# You should generate this and send to us the public key
 6MY_PVT_KEY = os.environ.get("MY_PVT_KEY")
 7
 8# Loadsmart will provide you with this UUID
 9MY_ISSUER = os.environ.get("MY_ISSUER")
10
11MY_USER_ACCOUNT_ID = os.environ.get("MY_USER_ACCOUNT_ID")
12
13
14def generate_usr_sub(account_id):
15    return f"usr:{account_id}"
16
17
18def generate_token(issuer, private_key, subject):
19    now = datetime.now()
20
21    # convert to unix timestamp
22    issued_at = int(now.strftime("%s"))
23    expires_at = int((now + timedelta(minutes=1)).strftime("%s"))
24
25    data = {"iss": issuer, "sub": subject, "exp": expires_at, "iat": issued_at}
26
27    token = jwt.encode(data, private_key, algorithm="RS256")
28    return token
29
30
31def generate_usr_token():
32    subject = generate_usr_sub(MY_USER_ACCOUNT_ID)
33    return generate_token(MY_ISSUER, MY_PVT_KEY, subject)
34
35
36def generate_sys_token():
37    return generate_token(MY_ISSUER, MY_PVT_KEY, "sys")

The code sample above can help you generate tokens for usr calls and sys calls.