Upgrading fmAccounting Link (Xero Edition) to OAuth 2.0

Last year Xero began the transition from using OAuth 1.0a for authenticating with the Xero API to OAuth 2.0. We wrote about our plans for OAuth 2.0 and fmAccounting Link (Xero Edition) back in December and released an update shortly afterwards that supported OAuth 2.0. This was mainly aimed at new customers as Xero removed the ability to create new OAuth 1.0a Private Apps in December and we needed a solution for new customers who could only create OAuth 2.0 apps to integrate with.

Existing customers who have been using fmAccounting Link (Xero Edition) prior to December 2019 also need to start planning the transition to OAuth 2.0 as Xero will be removing support for OAuth 1.0a Private Apps in 12 months (you have plenty of time to make the change). Here are the critical dates that you need to be aware of:

• 2nd December 2019: Developers could no longer create new OAuth 1.0a apps (if you need to create a new private app before June 2020 get in touch and we’ll show you how to do this for the next few months if necessary)
• December 2020: you should aim to have your existing integration upgraded from OAuth 1.0a to OAuth 2.0 by the end of the year
• 30 September 2021: OAuth 1.0a will no longer be supported for any integrations. You must have upgraded by 30 September 2021 or your existing integration will stop working (the original deadline of March 2021 has been extended for private apps only).

You can read more about why Xero are changing to OAuth 2.0 here and they have an FAQ on OAuth 2.0 as well. Since the initial release last year they have released a number of improvements to OAuth 2.0 to make for a faster and more seamless authentication process.

If you’re not sure where to start we have some good news for you – we’ve done all the hard work and have 2 new versions of fmAccounting Link (Xero Edition) that support OAuth 2.0. We’ve invested hundreds of hours of development time over the past few months in preparing these updates to have them available as soon as possible so you have as much time as possible to complete the upgrade.

If you’re looking to upgrade your fmAccounting Link (Xero Edition) v1 integration from OAuth 1.0a to OAuth 2.0 we’re pleased to have the following options available.

fmAccounting Link (Xero Edition) v1

Since we first released fmAccounting Link (Xero Edition) back in 2014 we’ve been releasing free updates to v1 for all customers ever since. That’s almost 6 years of free updates which we are very proud of and we’ve decided to also provide a free update to all existing customers to the OAuth 2.0 version. This is a major update from Xero and we didn’t want to leave our hundreds of customers all around the world without an option to update here (see important dates above).

All existing fmAccounting Link (Xero Edition) v1 customers can download the latest v1 release (v1.97 or later) which now supports OAuth 2.0 only. To download the latest v1 file just use the same link on your original order email (contact us if you can’t find the email or need the link to be reset etc) or if you created an account at the time of ordering you can login to our site and download it from your order history page.

We have a dedicated page (see below) that outlines the changes between the OAuth 1.0a and OAuth 2.0 versions and what changes you will need to make if you wish to upgrade an existing version/integration. You can always just use the new file and migrate your data across and perform the initial one off OAuth 2.0 authentication if you haven’t customised or integrated with other FileMaker solutions.

fmAccounting Link (Xero Edition) v1 OAuth 2.0 Update Guide

fmAccounting Link (Xero Edition) v2

As well as providing a free update to v1 of fmAccounting Link (Xero Edition) we’ve also released a new version that supports OAuth 2.0 and no longer requires a FileMaker plug-in to communicate with the Xero API. As we mentioned back in December one of the benefits of the move to OAuth 2.0 is that we can finally remove the plug-in dependency for authenticating with the Xero API that was necessary when using OAuth 1.0a and Xero private apps. This has been the reason why we haven’t been able to release a version of fmAccounting Link that runs natively on the FileMaker 16 Platform or higher without requiring a FileMaker plug-in. There are a number of benefits to removing the plug-in dependency, including faster API request processing and the ability to use other clients like FileMaker Go (without being connected to FileMaker Server).

fmAccounting Link (Xero Edition) v2 is now available and is a paid upgrade (customers who purchased v1 on or after 1 December, 2019 are entitled to a free upgrade!). All v1 customers are entitled to a 50% discount and you should have received your discount coupons in our initial mailout. Please get in touch if you haven’t received your coupon for the free or discount upgrade.

fmAccounting Link (Xero Edition) v2 looks and feels similar to v1 but under the hood it is completely different. We’ve updated every script that touches the Xero API but it all works in a very similar manner. We’re now using native FileMaker script steps and functions which were first introduced in the FileMaker 16 platform, so you must be running FileMaker 16 or higher to use fmAccounting Link (Xero Edition) v2. We’re now using JSON for all data that we send and receive to Xero and are no longer using calculation fields to store the data payload to upload to Xero (we create a calculation as part of the upload scripts). Check out our v2 update guide below for further details on the changes from v1 to v2 that you need to be aware of.

fmAccounting Link (Xero Edition) v2 Update Guide

If you don’t have the time or resources to complete the upgrade to OAuth 2.0 please get in touch as we are available for consulting to work with you on upgrading your existing integration to either v1 or v2 of fmAccounting Link (Xero Edition).

OAuth 2.0 App Setup and Authentication

The way you authenticate with the Xero API changes from the old OAuth 1.0a private app setup where you exchanged a set of keys to the new OAuth 2.0 where a user has to login to Xero to approve access to your new app/integration. We have a video covering the OAuth 2.0 App Setup on our videos page (the authentication process is the same for both versions).

As part of the OAuth 2.0 authentication fmAccounting Link will store the following for the Organisation your authenticated with:

At the successful completion of the OAuth 2.0 flow you will be granted an access token to act on behalf of the user as well as a refresh token. Access tokens expire after 30 minutes and you can refresh an access token without user interaction by using a refresh token.

N.B. Unused refresh tokens expire after 60 days. If you don’t refresh your access token within 60 days the user will need to reauthorize your app.