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_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
![]() | 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_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.