# Notice of change - Recommended header fields for GET /accounts endpoints and the PUT /tokens/{tokenId}/cancel endpoint

Issued: 24th October 2023 | TB-1236

Updated: 10th November 2023

Updated: 5th April 2024

Updated: 11th July 2024

 

### What's changing?

Token.io recommends that when a user has logged in to a TPP’s application and is initiating a request, the TPP should include the user's IP address in the `token-customer-ip-address` header field.


```json
curl --location 'https://api.token.io/accounts' \
--header 'Authorization: Basic <AUTH_TOKEN>' \
--header 'Content-Type : application/json' \
--header 'token-customer-ip-address: 192.0.2.1' \
```

**Providing public user IP addresses is a useful for TPPs, as in many cases validation is applied on the bank's side.
If the user IP address is not provided for AIS use cases, they may be treated as a user-offline. In this scenario, consent will only be given for three (or similar) requests per day.
It is not Token.io's policy to collect user IP addresses for all API clients/banks, as this information is rarely contained in the bank documentation. Moreover, banks may be implementing this validation without notifying Token.io, so this information will become outdated, if collected.
According to NextGen 2 standards, it is mandatory that the forwarded IP address header field consists of the corresponding HTTP request IP address field between the user and TPP. If not available, the TPP should use the IP address used by the TPP when submitting the request.
**

This recommendation applies to the following [/accounts](../../api/reference/Accounts) endpoints, for AIS requests:

- [GET /accounts](../../api/reference/Accounts#operation/GatewayService.GetAccounts)
- [GET /accounts/{accountId}](../../api/reference/Accounts#operation/GatewayService.GetAccount)
- [GET /account-balance](../../api/reference/Accounts#operation/GatewayService.GetBalances)
- [GET /accounts/{accountId}/balance](../../api/reference/Accounts#operation/GatewayService.GetBalance)
- [GET /accounts/{accountId}/transactions](../../api/reference/Accounts#operation/GatewayService.GetTransactions)
- [GET /accounts/{accountId}/transaction/{transactionId}](../../api/reference/Accounts#operation/GatewayService.GetTransaction)


and the following [/tokens](../../api/reference/Tokens) endpoint, for AIS and PIS requests:

- [PUT /tokens/{tokenId}/cancel](../../api/reference/Tokens#operation/GatewayService.CancelToken)


In addition, the following header fields are recommended for use with the [PUT /tokens/{tokenId}/cancel](../../api/reference/Tokens#operation/GatewayService.CancelToken) endpoint, for both AIS and PIS requests:

- `customer-initiated`
- `token-customer-device-id`



```json
curl --location 'https://api.token.io/tokens'
--header 'Authorization: Basic <AUTH_TOKEN>' \
--header 'Content-Type : application/json' \
--header 'token-customer-ip-address: 192.0.2.1' \
--header 'customer-initiated: true' \
--header 'token-customer-device-id: 00000000-00000000-01234567-89ABCDEF' \
```

Please refer to the [Common request headers](../integration-considerations/api-basics#Common) section in API Basics and the [API reference](../../api/reference) for further information about these fields.

### What problem will this solve?

Using the `token-customer-ip-address` header field will enable Token.io to send the correct IP address to the bank, and will therefore improve conversion rates. In addition, some banks require this information for their Anti Money Laundering (AML) policies.

Using the `customer-initiated` and `token-customer-device-id` header fields will let the bank know whether the API call was explicitly initiated by the user and provide further information about the user's device. This information will help in tracking fraudulent transactions.

### Does this change affect you?

This change will impact any customer initiating a request to Token.io when the user is in session.

### What action do I need to take?

This is an optional change and you can implement none or any combination of the headers. To apply the change you'll need to:

- capture the user's IP address and present it in the `token-customer-ip-address` header field.
- determine whether the API call was initiated by the user and present this information in the `customer-initiated` header field, in Boolean format.
- capture the id of the users device and present this in the `token-customer-device-id` header field.


### When will this change apply to all impacted customers?

This change is effective immediately.

### Where can I get further information?

For assistance with the above and other operational aspects of the Token.io Account-to-Account Infrastructure, please contact [Token.io Support](https://support.token.io/).