An application can access data in an IOL account in different ways, provided the data owner (IOL account owner) accept to share data access permissions with the application in any of these ways:
- Application is allowed to read data from the IOL account using API tokens
- Application is allowed to read data from the IOL account by IOL pushing update notifications to the application using webhooks
- Application is allowed to write/edit data to the IOL account by using API tokens
In addition to approving different access types, a data sharing connection can have fine-grained permissions on different entity types, and even have data filters and exclude certain sensitive fields.
To allow an application to access data in an IOL account, the IOL account must be set-up with API token configurations and/or webhook configurations that enable IOL to share data access with the application (configurations for API tokens and webhooks are created automatically by the application connection concept outlined in this chapter), and the account owner must accept data sharing with the application.
These are the steps in the process of creating an application that can access data from IOL accounts:
- Get an IOL Developer account – contact Logtrade support for details.
- Register your application in the IOL system administrator portal of the IOL Developer account. Make sure to register what “Oauth2 scopes” (permissions) the application need from the IOL data owner account. Never ask for more data than needed. Example: A carrier software likely needs to receive TransportInstructions from Shippers as webhook notifications, and need to write TransportStatus updates into the Shippers IOL account using API tokens.
- Create the application, and use API calls to edit data and use API calls and/or webhooks to receive data from a (currently undefined) IOL data owner account
- Implement the IOL application connection concept (outlined in this chapter), to enable data owners to simply click a button/link to share data from their account with your application. The IOL application connection concept performs a key-exchange handshake and also autoconfigure any API token configurations and webhook configurations in the data owner’s IOL account.
- Your application shall dynamically build the Connection URL (data sharing request link) for each data owner your application wants to access data from
Once your application is registered in IOL, uses IOL API’s and/or webhooks for data access, and has implemented the application connection system as outlined in this chapter, your application is ready to integrate with any number of IOL data owner accounts (with one data sharing connection set-up to each of them, once the data owners have accepted the data sharing request).
When an application wants access to the data in an IOL account, this is the process of setting up a data sharing connection between a specific IOL data owner account and the application:
- The application itself – or the application owner/user – must share the Connection URL (data sharing request link) your application has assembled dynamically for this specific IOL data owner account with the owner of that IOL account, for example by sending them the Connect URL link in an email asking for permission to let your application access their data.
- When the IOL data owner receives the Connect URL that requests data sharing with the application, they can click on it to initiate the process of accepting data sharing with the application. When they do so, they are redirected to an IOL panel that display what data sharing permissions this application is requesting.
- The IOL data owner can view the permissions, and if he or she agrees, clicks on the APPROVE button to accept data sharing with this application. A data sharing connection is then setup automatically between the IOL data owner account and the application, security keys/tokens are exchanged automatically, and any API token configurations and/or webhook configurations are created automatically in the IOL data owner account, enabling data sharing with the application.
- The application will now be able to read/write data in that IOL data owner account as per the requested and proved permissions.
Additionally, an application can connect to an IOL data owner account in two different ways:
- Single-account applications get data to the application itself only, and not to a specific account/user of that system. A typical example is an in-house developed carrier TMS system that receives shipments (IOL TransportInstruction entities) from shippers. There is only one carrier using this software, so the data owner do not need to know which user/company account at that software they accept data sharing with and is getting the data.
- Multi-account applications can maintain multiple connections on behalf of different users/accounts of that system. A typical example is a commercial-of-the-shelf TMS system that is provided by one software company, and used by many different carriers. In this case, the data sharing is setup between the shipper’s IOL data owner account and a particular user/account of the application.
All actors (both sides of the application connection being set-up) must have an IOL account, to get a world-wide unique IOL Organization Id, which identifies them in the key-exchange and let both parties know who the other party is.
This chapter describes the IoL application connection and token exchange mechanism in more detail, and how you can integrate your applications with IOL. The underlying aim behind the application connection and token exchange concept is to provide a means by which data belonging to a data owner can be shared with an application in a manner that is very easy for the IOL data owner, including automatic creation of API token and webhook configurations.
A C# / .NET example of how to implement the application connection and token exchange mechanism is available here: https://github.com/logtrade-technology-ab/data-sharing-examples/tree/main/OAuth
You can read about how to register, manage and connect to applications that you define in IoL: