Authentication

CargoDocs API Authentication & Authorization

CargoDocs APIs use the OAuth 2.0 protocol for authentication and authorization. CargoDocs supports standard OAuth 2.0 scenarios for web server, client-side, installed, and limited-input device applications.

Obtaining Client Credentials

To begin, the CargoDocs API team usually provides OAuth 2.0 client credentials upon request to our customers for Sandbox, UAT, and Production environments. Then your client application requests an access token from the CargoDocs Authorization Server, extracts a token from the response, and sends the token to the CargoDocs API.

This page gives an overview of the OAuth 2.0 authorization scenarios that Cargo and provides links to more detailed content. For details about using OAuth 2.0 for authentication, see OpenID Connect.

OAuth 2.0 Steps

All applications follow a basic pattern when accessing a CargoDocs API using OAuth 2.0. At a high level, this is a two-step, straightforward process to follow.

1. Obtain OAuth 2.0 Credentials

Each customer retrieves their own OAuth 2.0 credentials through the CargoDocs API support team. Credentials consist of a client ID and client secret that are known to both CargoDocs and your application. The set of values varies based on what type of application you are building.

❗️

Securing User Credentials

Customers/Partners must ensure to secure the client ID and secret to avoid any inconvenience.

2. Obtain Access Token

Before your application can access private data using a CargoDocs API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs.

📘

Authorization URL

CargoDocs API access token is obtained by passing Client Credentials to our authorizationUrl which is available at:

https://api.domain.cargodocs.com/v3/common/auoth2/token

Sample Token Generation

Here is a sample cURL to generate a token.

cURL

curl --location --request GET 'https://api.cargodocs.com/v3/common/oauth2/token' \
--header 'Password: vH3OJ4xS$5' \
--header 'Username: Bumblebee'

Upon successful authentication, CargoDocs authentication responds back JSON object containing token.

JSON

{
    "token": "eyJraWQiOiJ3YitJMjNzOWRCNUh0cjBhQXVwTHVjeFwvUFhWREhlVEcyQWpTNnkyNFBjYz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMjNmMDNlNi1lNDIwLTRjODEtOGIzZS1hOGM5MmYzZGQ0OTQiLCJkZXZpY2Vfa2V5IjoiZXUtd2VzdC0xXzMzODMxNzlmLTAyNTQtNDE4MC1hZWM4LWNhN2Q3ZTVmZTkyNCIsImV2ZW50X2lkIjoiODQ3NGEyZWQtZTYzZC00NmY5LWJlNmMtMWViNTc0YzcwZGNjIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJhd3MuY29nbml0by5zaWduaW4udXNlci5hZG1pbiIsImF1dGhfdGltZSI6MTY0NTUzMjIwNywiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmV1LXdlc3QtMS5hbWF6b25hd3MuY29tXC9ldS13ZXN0LTFfSnN6bUZoejRoIiwiZXhwIjoxNjQ1NTM1ODA3LCJpYXQiOjE2NDU1MzIyMDcsImp0aSI6ImNkODlhMDBhLTg3MWUtNDkzYy1hNTIwLWM3OWU2ZGEwOTUxMCIsImNsaWVudF9pZCI6IjNwZHZrbWEzdDM5bnNxamFyamlmM2k0ZmlkIiwidXNlcm5hbWUiOiJWb2x0cm9uIn0.banOsyWt57Um_XdqteVBuRDIim8Q_KG1IMRLc7bsXJNoI_fmQi95sc7a2-fCyjFG4z4ryA5dmYaXGdX3Gk7PFUyr5EYhJavt18OY7jbdU1IUNRhiI4zlngev4ibCWiTp6HSwDk9NOao8v8qgjUVwWVuNcbnNbmjnyIs0-m8NS3FtkoeC4_V5HVWYrd2XCQJFheG50qu2I2RXHmd-JfiJAGa9ALSDVIUYElkm4m0xUucHqXybwzRHszhCyDVpmR4Iz0BI8EMe5AAkJtN-rW_UJTMDlQeL7qCJJsasoeMcHWLgr3Dqq0Y21FgQu2K7JE0ZpvnRGjAE0YD4X3quXEW4NA"
}

❗️

Token Expiry

Each generated token is valid for 15 minutes only.