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 :code:`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`_

.. literalinclude:: /code/jwt.py
    :caption: jwt.py
    :name: jwt-py
    :language: python
    :linenos:

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

.. _JWT: https://jwt.io/
.. _API documentation: https://developer.loadsmart.com/api/index.html
.. _share a capacity: https://developer.loadsmart.com/api/index.html#tag/Capacity/paths/~1api~1v2~1capacity/post
.. _search carrier endpoint: https://developer.loadsmart.com/api/index.html#tag/Carrier/paths/~1api~1v2~1carrier~1search/get
.. _PyJWT: https://pyjwt.readthedocs.io/en/latest/