1. Introduction

1.1. Who should read this guide

This document is intended for CargoX partners and clients, who with to integrate the CargoX Platform into their online system. It describes the basis of integration with the system through all available interfaces. Intended audience therefore includes developers and interested parties.

1.2. What is the CargoX Platform

CargoX Platform is a Blockchain Document Transfer platform. It provides the world’s easiest way to share documents, and gives you the the tools for secure and instant transactions of those documents.

Any type of document can be transferred with various degrees of blockchain support:

  • from simple documents – such as invoices or manuals

  • through "blockchain-supported" documents – such as certificates

  • and finally original documents: documents where transfer of ownership is an essential part of the document workflow --- such as bill of lading documents and bills of exchange

All this is possible thanks to the neutral, public blockchain - the glue that will bind the businesses of the future.

CargoX Platform simplifies the use of blockchain by hiding away the complexity of Smart contracts from the user and providing an easy-to-use REST interfaces for interaction.

1.3. The platform infrastructure

CargoX has created a platform, which enables you to transfer the different documents, including the Document of title between the parties. The platform itself is called is available at the domain https://cargox.digital/.

The platform itself is composed of the following parts:

  • The blockchain part, a Smart contract on the Ethereum platform; this part of code is responsible for transferring document ownership and recording document authenticity information.

  • The CargoX platform, which wraps around the blockchain code, adds functionality such as address books and document storage, and allows users to interact with the application through well-known REST interfaces.

  • The CargoX database, which stores non-blockchain data (such as company details, contact books, address to name mappings, etc).

  • The IPFS storage, which holds all the documents. Documents on the IPFS are encrypted and fault-tolerant by design.

  • The front-end application, developed using the services provided by the web application and allowing the users to use the application through a graphical user interface.

_images/cargox-platform-communication-flow.gif

Note

Everything available through the web interface is also available via an API. Even more – the API introduces some advanced functionality, which is not available through the GUI itself.

1.4. Security at CargoX

1.4.1. Private keys

CargoX heavily relies on public key infrastructure to provide security. All critical actions need to be signed by the user's private key.

Important

Ethereum private keys are used to sign all critical transactions within CargoX Platform. This includes things like document transfers, confirming your user's blockchain keys etc.

Usually a user would use the private key to interact with the blockchain directly. However, to simplify things, CargoX acts as a relayer:

  • A unique message is generated by the platform. This message is send to the user to sign.

  • The signed message is relayed to the blockchain smart contract.

  • Smart contract verifies the signature and executes the transaction on behalf of the user.

CargoX has no access to this private key at any time and it is the sole responsibility to the user to take good care of the key. If the key is lost of compromised, CargoX has no way to restore or reset such key.

1.4.2. Secure access

Users and applications access the platform exclusively through the main web page --- https://cargox.digital. Access is protected by strong TLS security and information cannot be seen or modified by a third party.

1.5. Getting started

CargoX Platform is simple to use. For any advanced type of integration, though, you will need an account first. To create an account see the following chapter.

There are are several ways of integration CargoX Platform into your workflow, depending on your needs:

  • Affiliate linking. This means you get an affiliate link and every signup through that link is attributed back to you. This can be upgraded by white-labelling a solution, where the platform is skinned in your colours.

  • If you're providing services to your own users, you can integrate CargoX directly into your workflow:

    • The platform may be IFRAME-ed into your existing application, if you're running on the web. CargoX provides seamless login, which allows your users to transparently switch to the platform without interruptions.

    • You may completely embed CargoX into your workflow by calling the API directly. This way your users don't need to log through the CargoX's GUI at all and can stay completely within your application. 1

  • If you just want to offer users a simple way to upload documents to CargoX, see Using external sources.

Read more about it in the integration scenarios chapter.

1.5.1. Create a CargoX account

Before you can use the any advanced integration scenarios (affiliate linking or API integration) you need to have an account on the platform. The account doubles as your "regular" account so you can use it to send and recieve documents as well as execute advanced integration calls.

Go ahead and create an account now.

1.5.2. Third-party authorization and authentication

Note

Certain calls still require a signature with a private 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 private keys 1 – for example if the user is only viewing the documents, no private key is necessary.

CargoX platform uses OAuth for user and API authentication. Each application is issued a custom client_id and client_secret, which it uses then to identify itself against the platform and authorize users. Users are then identified by their private keys and/or username and password.

Attention

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 a blockchain key.

1.5.3. Explore the API

The API is based on RESTful principles and is publicly available for browsing.

Tip

Navigate the browsable API by visiting the generated documentation. More info about all available endpoints is available on a separate page.

1(1,2)

If you use this integration type, you will need to think about how you want to handle user's private keys. These can be either stored within your system or left to the user. Each of these choices has its benefits and pitfalls. Read more about it on the storing private keys page.