Implementing Token Exchange

These notes are provided for application developers responsible for developing the application token exchange mechanism.

Read about how to implement token exchange in the following sections:

Messaging

IoL will initiate the token exchange process by posting to the Authorization Callback URL of the registered application specified by the client ID supplied with the Connection URL.

A number of parameters are supplied, for example message type, state, client ID, that the application can use for its own internal verification processes.

The application provides the authorization webhook URL endpoint which is called by IoL.

Token Exchange Message

The JSON-formatted token exchange message sent to the application from IoL looks like this:

{
   “message_type”: “connection_successful”,
   “access_token”: “awrxqbkfp8c9tprayc9ziemiirg9ixi6fkjezcsp”,
   “refresh_token”: “hjklmbkfp8cspg9ixispsednabeerwinewhisky”,
   “state”: “request6066”,
   “client_id”: “8EsgmTcZYkC03L5tvm9999”,
   “token_type”: “Bearer”,
   “connection_id”: “asdghij78ewty”,
   “accepting_party”:
   {
      “name”:“ÅkesIT AB”
      “legalPartyID”:”https://www.anydomain.com/l.abcd1234
   }
}

Where:

message_type  Indicates the type of the message being sent:
* connection_successful – the data owner has successfully granted access to their data
* connection_rejected – the data owner has rejected access request
* connection_revoked – the data owner has revoked access to the connection
access_tokenThe API-generated access token to be used by the application as a bearer token when making requests to the IoL API for data. The parameter can be empty if the resultant scope relates only to webhook creation.
refresh_tokenThe API-generated access refresh token. The parameter can be empty if the resultant scope relates only to webhook creation. It can also be empty if the access token does not have an associated refresh token.

stateThe state identifier provided in the Connection URL
client_idThe client ID of the registered application provided in the Connection URL.
token_typeIndicates the type of authentication details required in response:
* Bearer – token is a bearer token
* None – only webhook scopes have been specified in the Connection URL.
connection_idThe ID of the data access connection with the registered application.
accepting_partyA collection of information about the data owner that accepted the connection request.
* name – name of the data owner
* legalPartyID – IoL account identity of the data owner  

The message is received in the HTTP Request body.

The Authorization Callback URL endpoint should not implement authentication.

Parameter Validation

IoL sends the client ID of the application and the state: information provided in the Connection URL. 

The IoL token exchange places no validation requirements on the application.  The application is free to perform whatever validation is required on the received token exchange data.

The response requirements are:

  • Communicate the result of any validation failure to IoL using appropriate HTTP response status codes.
  • In the case of success, return a HTTP OK status code.

Example JSON Messages

This message is sent when the data owner has successfully granted access to their data and a connection has been created.
This message is sent when the data owner rejects the request for data access.
This message is sent whenever the data owner revokes access to the connection.

Example C# Class

    public class ApiClientRequestModel
    {
        [JsonProperty(PropertyName = "message_type")]
        public string MessageType { get; set; }

        [JsonProperty(PropertyName = "state")]
        public string State { get; set; }

        [JsonProperty(PropertyName = "client_id")]
        public string ClientId { get; set; }

        [JsonProperty(PropertyName = "access_token")]
        public string AccessToken { get; set; }

        [JsonProperty(PropertyName = "refresh_token")]
        public string RefreshToken { get; set; }

        [JsonProperty(PropertyName = "token_type")]
        public string AuthenticationType { get; set; }

        [JsonProperty(PropertyName = "connection_id")]
        public string ConnectionID { get; set; }

        [JsonProperty(PropertyName = "accepting_party")]
        public Dictionary<string, string> AcceptingParty { get; set; }
    }

Configure Response

This section describes the response from your application to the token exchange message from IoL.

Successful Response

When having successfully performed any validation and generated a bearer token, the application should return the following data in the body of the HTTP response.

{
   “access_token”: “637896010776878367”,
   “token_type” : “Bearer”,
   “accepting_party”:
   {
      “name”:“ÅkesIT AB”
      “legalPartyID”:”https://www.anydomain.com/l.vwxyz0987
   }
}

Where:

access_tokenThe access token to be used with webhooks configured by IoL for the connection.

 
token_typeIndicates the type of authentication details required in response: Bearer – token is a bearer token   
accepting_partyA collection of information about the application responding to the request. name – name of the carrier or application legal partylegalPartyID – IoL account identity of the carrier or application requesting data access to the data owner’s data  

This is an example C# class for serializing the data from HTTP Response:

    public class ApiClientResponseModel
    {
        [JsonProperty(PropertyName = "access_token")]
        public string BearerToken { get; set; }

        [JsonProperty(PropertyName = "token_type")]
        public string AuthenticationType { get; set; }

        [JsonProperty(PropertyName = "accepting_party")]
        public Dictionary<string, string> AcceptingParty { get; set; }
    }

If successfully processed, return a HTTP 200 OK status code.

And the JSON-formatted message:

Failure Response

In the event of a failure to validate or some other internal failure, return an appropriate HTTP status code.