Token Exchange in IoL

To facilitate the exchange of tokens between would typically have required manually configuring IoL, requiring the adding relevant tokens and webhooks to IoL.  This is a complex process that could result in errors and incorrect configurations, especially as the number of tokens and webhooks increase with the number of applications wishing to access the data of data owners.  This mechanism is simplified by using a protocol based on OAuth2 for token exchange, which permits the granting of data access by a data owner, and the exchange of relevant access tokens between parties.

Logtrade IoL token exchange provides a mechanism to automatically generate an IoL access token when a data owner grants access to their data.  This access token is then exchanged with an application and receives an application-generated access token in return.  As part of the token exchange process, the IoL API will also automatically create webhooks where required.

Assumptions

It is assumed that:

  • The reader has some experience of using the IoL Admin Portal.
  • The reader is familiar with IoL webhook concepts and their development.
  • The read is familiar with token management in the IoL Admin Portal.
  • That the reader’s IoL account is correctly configured to permit access to the IoL token exchange features.
  • The reader is familiar with UML sequence diagrams, JSON and C# programming.

IoL User Account Configuration

To access the features presented in this document the following IoL configurations must be applied to the user’s login account:

  • Application developers must be members of the IoL Developer Program, which will enable all features for managing registered applications and Authorized connections.
  • Data owners must have an IoL data owner license, which will enable the Authorized connection management features.

Please speak with your Logtrade account manager to establish the correct configuration for your account.

Glossary of Terms

Access token  The token generated by the IoL API when creating a connection.  The access token limits access to data as requested by the application.  This token is used as the bearer token by the application when requesting data from and interacting with the IoL API.  
Application  The 3rd party application developed by the application developer.  The application incorporates the ability to communicate with the IoL API, as well as implementing webhook endpoints to be called by the IoL API.  
Application developer  The corporate entity developing the application.
Authentication URL  The callback URL called by the IoL API in response to a data owner granting or rejecting access to their data.  
Bearer token  The token returned by the application in response to the request sent by the IoL API to the Authentication URL.  The bearer token is used when the IoL API creates the webhooks.  
ClientID  A unique identifier assigned to each registered application.
Connection URL  This is a URL generated by the application developer which includes the types of data the application would like to access.  The Connection URL is published, e.g. sent via email, messages, to a data owner by the application developer. On entering the Connection URL into a browser, the data owner is presented with details of the data being requested.  The data owner can at this point accept the request or reject the request.  If the data owner accepts the request, tokens will be securely exchanged between IoL and the application.  If the request is rejected, the application is notified that the request has been rejected by the data owner.  
Consent screen  A screen presented to the data owner showing the data scopes requested by the application.  The data owner may accept or reject the request by the application for data access.  
Data owner  The corporate entity that owns the data associated with a Logtrade account and stored within the Logtrade servers.  
Entity association  The IoL mechanism by which one or more entities are associated with each other – for example, a TransportInstruction entity with an Asset entity.  Whenever either of these is updated, the application will be notified of this change if the registered application has a configured associated entity webhook URL.  
Grant access  The operation by which a data owner permits access to their data to a requesting application.  
Registered application  A representation of the 3rd party application within IoL.  An application must be registered with IoL.  A registered application incorporates details of the scopes that restrict the type of data operations an application connecting to it can perform.  Any number of connections can be assigned to a registered application. Other parameters define for example, name, description, and application URL, and webhook URLs.  
Scope  Scope is a mechanism to limit an application’s access to a data owner’s data. An application can request one or more scopes, this information is then presented to the data owner in the consent screen, and the access token issued to the application will be limited to the scopes granted.  
State  A unique identifier provided by the application.  State participates in the token exchange between the IoL API and application and is sent to the application during the granting of consent by the data owner.  The significance of state is application-dependent and can relate to, for example, account details of an application user.  It might be used by the application to validate a request from IoL API during token exchange.  
Token exchange  The process whereby Iol API communicates with application sending an access token to the application, and a bearer token in reply from the application.  
Webhook  A webhook is a user-defined callback method defined with the registered application.  It is triggered by an event in the IoL API when ,for example, an application requests data from IoL, or whenever an application pushes a data update. For a webhook to trigger a valid URL to the application webhook endpoint must be provided in the registered application by an application developer.  The token to be used when calling the webhook is supplied in the response by the application during token exchange. A webhook is only created when defined by a scope supplied with a Connection URL. A webhook is triggered by IOL upon entity creation, edit or deletion.