- Authentication: the process for authenticating with Xero changes from OAuth 1.0a to OAuth 2.0. You now need to do a one time approval via a Web Viewer that requires the Xero customer to approve the app. See our video for further details here.
- API request Header: each request to the Xero API now requires new headers to be set for each request
- Token Refresh: you need to check, once you have completed the one off initial authentication, that your Xero token hasn’t expired and to call the script to silently refresh this if it has
We’ll be using the fmAccounting Link (Xero Edition) Single Organisation.fmp12 file as the guide here, but the process is similar if you’re using the fmAccounting Link (Xero Edition) Multiple Organisations.fmp12 version.
If you use one of the Database Design Report analysis tools like BaseElements or FMPerception you can use these to run a comparison report between your current version/integration and the new OAuth 2.0 version to identify the changes. We’ve used BaseElements to generate a report showing the differences between the last OAuth 1.0a version (v1.969) and an OAuth 2.0 version (v1.975) which you can download here.
Authentication
The process for authenticating with the Xero API obviously changes quite significantly as part of the move from OAuth 1.0a to OAuth 2.0. You’ll need to create the following new fields in the Interface table (you can copy/paste these across using FileMaker Pro Advanced):
ClientID ClientSecret RedirectURI AccessTokenExpires TenantID XeroAccessToken XeroRefreshToken
We’ve created a new layout for the authentication process (you could also use a popup window for this etc)
Xero Authentication
which has the Web Viewer that is used for the OAuth 2.0 authentication process.
You can import the following scripts which are used to start and complete the OAuth 2.0 authentication:
Xero Authentication - OAuth 2.0 Start Xero Authentication - OAuth 2.0 Complete Xero Authentication - OAuth 2.0 Refresh Access Token Get Organisation
The existing Xero Preferences layout has been updated with these new fields and buttons that call the new scripts – once again you can copy/paste these across. Once you have completed updating the fields, layouts and scripts you can test the OAuth 2.0 authentication process.
We have a video showing the OAuth 2.0 authentication flow in action on the fmAccounting Link (Xero Edition) Videos page.
OnFirstWindowOpen Script
You will need to update the OnFirstWindowOpen Script script to set the $$fmXeroAuthenticated global variable if you have previously authenticated with Xero so you don’t continue to be prompted to authenticate unnecessarily.
With OAuth 1.0a we set this global variable when the Xero Authentication script was performed, typically once per FileMaker session. With OAuth 2.0 you need to perform the initial authentication and then continually refresh the Xero access token as it expires. As you typically only need to perform the initial authentication once we can check to see if this has been performed in the OnFirstWindowOpen Script script which runs each time a user opens the file.
We have added a number of tests in this script for each FileMaker Client (Web Publishing Engine, Server and Pro) that you can copy/paste to set the global variable to prevent you from having to unnecessarily authenticate each time you open the file:
You can copy/paste these across from the OAuth 2.0 script at the appropriate places to ensure the $$fmXeroAuthenticated global variable is set accordingly each time the user opens the file.
HTTP Header Changes
As part of the change to authenticating using OAuth 2.0 each request to the Xero API needs to specify new HTTP Headers. Here’s a comparison of the old and new using the Get All Invoices – XML script as an example. With OAuth 1.0a we just set the Header once in the script here:
In the above example you can see it is only setting a single Header.
With OAuth 2.0 we need to set the Header for each iteration of the loop like this:
We also need to set multiple headers like these in this example:
BE_HTTP_SetCustomHeader ( "Accept" ; "text/xml" ) & BE_HTTP_SetCustomHeader ( "Authorization" ; "Bearer " & InvoicesPreferences::XeroAccessToken ) & BE_HTTP_SetCustomHeader ( "Xero-tenant-id" ; InvoicesPreferences::TenantID )
For each script that you’re currently using (e.g. if you’re just uploading Contacts, Invoices and Payments you just need to update those scripts for now) you’ll need to update the steps that set the HTTP Headers when making the requests. Once again you can copy/paste these across from the OAuth 2.0 script.
Token Management
As part of the OAuth 2.0 authentication fmAccounting Link will store the following:
At the successful completion of an OAuth 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.
As access tokens expire after 30 minutes you will need to check to see if they have expired before you make a request to the API and refresh them first. There are 2 occasions when you will need to perform this:
- before every request to the API (e.g. before attempting to download or upload to Xero)
- if performing a bulk action within a loop (e.g. downloading a batch of Invoices using pagination) you will need to check the token expiry within each iteration of the loop
Here are some screenshots showing this in the Get All Invoices – XML script at the beginning before making the first API request:
and then within the loop to check before making the next API request in the next iteration of the loop:
Once again you can copy/paste these across from the OAuth 2.0 script.
We recommend testing each change that you make as you go. First update the Authentication process and ensure you can successfully authenticate using the new OAuth 2.0 flow. Then update a script that you currently use and test that it works with the new OAuth 2.0 changes.
We have updated the fmAccounting Link (Xero Edition) FAQ with some OAuth 2.0 specific issues so please review that if you’re encountering issues with the OAuth 2.0 changes.