Notice: Upcoming Access Token Authentication changes


We’ve got some important changes to announce. Please have a read below, and if there are any questions, please reply and we can hopefully answer your queries!

In accordance with regular security reviews of our systems, we at FreeAgent have decided to update our token lifecycles and procedures. Don’t worry, things won’t break overnight, but as developers, there are some elements of your applications that you may have to make changes to.

Authorisation Tokens: These tokens allow the application to initially be granted access to FreeAgent data.

Action: The lifetime on these tokens will be revised down from one hour to fifteen minutes. No action by developers is needed here other than to note the lifetime changes.

Access Tokens: These tokens allow your application access to FreeAgent data.

Action: The lifetime of these tokens will be revised down from seven days to one hour. No action by developers is needed here other than to note the lifetime changes.

Refresh Tokens: These tokens allow the application to gain new Access Tokens and continued access to FreeAgent.

Action: Refresh tokens now return their lifetime, and are also returned when an Access Token is regenerated. Previously, when generating a new access token, the request and the response was as follows:

An application makes an HTTP Basic Auth POST to the FreeAgent Token Endpoint ( using the Client ID as the username and
Client Secret as the password and including the following in the POST body:

 * grant_type=refresh_token (required)
 * refresh_token=the refresh token code (required) 

For Example

Content-Type: application/json


If successful, the server would have returned a JSON response containing the new Access Token:




However, the new system slightly differs. The request made by the application is exactly the same

Content-Type: application/json


But, If successful, the response will be different. The server will return a JSON response containing the new Access Token, a Refresh Token and expiry fields for both:






You should store these values in your application. Going forward, we may decide to reduce Refresh Token lifetimes and expiry will become important in those contexts.





Why is this change being made?

Reducing the time tokens are valid for will reduce the impact of a token falling into the wrong hands, and therefore will increase the security of the FreeAgent application and our customer’s data.

When is this change coming into effect?

The change will come into effect on 18th May 2020. All Access Token refreshes should then be returning Refresh Tokens and their lifetimes, and all other tokens (as detailed above), will have had their lifetimes modified.

What if I need help?

We’re here, and always happy to help. Just respond to this thread and we’ll do what we can to help you. If you have details you don’t want to reveal publicly, post on the thread indicating so, and a member of FreeAgent staff will contact you privately.

Do I have to change anything on my account on

No, nothing needs to be changed there. You just need to update your application to store the Refresh Token Expiry Date. Not storing it will not break your application, but it is advised, as in the future Refresh Tokens may be issued with a shorter expiry date. If we make those changes in the future, we’ll advise on how to get a new Refresh Token.





FYI These changes are now merged into production and are now live. As always, find us here if you need help!




The rate limit docs say one can make up to 15 token refreshes per minute, and that all the limits are per user.

However this rate limit seems to be global rather than per user. Please could you clarify if this is true?

Many thanks in advance,



The rate limit is indexed by Access Token, so in this case it would be per user. Are you seeing throttling attempts on subsequent Access Token requests? If so, that would be a bug, and we’d investigate.




Yes I am: the request for the 16th distinct access token is throttled.




First and foremost, let me apologise for the inconvenience this has caused. We raised an incident internally and identified an area of the code that required tweaking. We’ve done this now, and you should no longer encounter throttling in this case. It will take a few minutes for this change to become live.

If you encounter any other issues, please feel free to contact us!

Cheers, Phil


Thanks for the quick response, Phil :slight_smile: