Skip to main content

Authentication

Cargamos employs an OAuth flow to authorize API calls. The sequence observed in the figure is followed.

Dropoff

Fig. OAuth Flow

This flow consists of the following steps:

  1. Shipper requests an access token: The shipper identifies themselves using their username and password, and Cargamos requests the access token from the OAuth server using these credentials. The endpoint used to request the access token is:
GET {host}/v1/login?key={key}

where the key parameter is provided to the shipper during registration (see the Registration section). The username and password are supplied using Basic authentication. Additional information can be found at Basic Authentication.

  1. Cargamos requests the access token from the OAuth server on behalf of the shipper.

  2. The OAuth server returns the access token, valid for 60 minutes.

  3. The obtained tokens are returned to the shipper. An example of the response is:

{
  "version": "1.0.0",
  "status": "OK",
  "timestamp": 1675978304058,
  "data": {
    "token": "el_token",
    "expiresIn": "3600"
  }
}

  1. The shipper uses the API, supplying the bearer token (access token) via the call's header. Additional information can be found at Bearer Authentication.

  2. Cargamos authorizes the call through the OAuth server.

  3. The OAuth server grants access.

  4. The action is taken and/or the requested resource is returned to the shipper.

If it's necessary to update the password, currently this can be done through the endpoint:

POST {host}/v1/password/recovery?key={key}

The mentioned endpoint returns a status code of 200, and subsequently, an email with a format similar to the one shown in the figure will allow the assignment of a new password by following the provided link.

Dropoff

Fig. Email for Password Reset

Notes and Recommendations
  • Access tokens always have a duration of 60 minutes.
  • It is recommended to rotate the password frequently.
Note:

New access tokens should only be requested when they expire. It is not necessary to request a new token every time a call is made (unless the token has already expired). Not following this recommendation may incur additional costs.