4. Authorization and authentication

4.1. Introduction

CargoX Platform uses OAuth for authentication. Each application is issued a custom client_id and client_secret which it uses then to identify itself against the CargoX application and authorize users.

Warning

Please keep these credentials safe. If credentials are compromised an attacker may be able to retrieve documents, change and add users and CargoX might not be able to detect or influence this.

The attacker, however, won't be able to change the document ownership, as this requires the use of a blockchain key.

Users are identified based on their blockchain keys and/or username and password. The basic workflow (for registered users) is defined below.

Note

Certain requests still require a signature with a blockchain key no matter how the user was logged in – for example transferring a document requires signing a challenge. Please bear in mind that not all users will require a blockchain key – for example if the user is only viewing the documents, no blockchain key is necessary.

4.2. Obtaining an access token

If a third-party system wants to access the specific API endpoint, it needs to obtain an access token for itself.

This is done by requesting a grant type of client_credentials:

Example

curl -s https://CLIENT_ID:[email protected]/oauth/token/ \
    --data="scope=read%20write&grant_type=client_credentials"

Response:

{
    // Access token to be used in Authentication: Bearer <token>
    "access_token": "WlMxwPLaAG3krmvJxyzkSiVgIGaPIdH",
    // Token expiry time
    "expires_in": 600,
    // Token type. Currently only “Bearer” is available
    "token_type": "Bearer",
    "scope": "read write"
}

This access_token may then be used to call the third-party API by adding Authorization: Bearer ACCESS_TOKEN header to your requests.