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
• Token Exchange Message
• Configure Response

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_token	The 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_token	The 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.
state	The state identifier provided in the Connection URL
client_id	The client ID of the registered application provided in the Connection URL.
token_type	Indicates 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_id	The ID of the data access connection with the registered application.
accepting_party	A 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

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_token	The access token to be used with webhooks configured by IoL for the connection.
token_type	Indicates the type of authentication details required in response: Bearer – token is a bearer token
accepting_party	A 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.