caret

Building a machine-to-machine integration

All Xero APIs require apps to operate on behalf of a user. Connecting your app to a Xero account requires a user to grant consent in a web browser. This can be challenging if you’re building a back-end integration that doesn’t have a user interface.

For integrations like these, our CLI tool XOAuth allows you to establish an offline connection with a Xero user’s account directly from the command line. No web development required.

Connecting your app to a Xero account

To get started, simply download the binary for your platform (Linux, Mac OS or Windows) from the Github repo. Once you have XOAuth installed, you run one command to setup your client and a second to make the connection.

The connection command will automatically open a web browser for the Xero user to log in and consent to your app. Once the user has given consent, all the tokens will be displayed in the web browser as well as being piped to stdout so you can use them in a script workflow.

Check the README for detailed instructions on how to use XOAuth.

Maintaining an offline connection

Xero’s access tokens have a limited lifespan of 30 minutes but they can be refreshed using a refresh token. This means your integration can maintain an offline connection without needing the user to re consent to your app.

To keep the connection alive there are just a couple of points to keep in mind:

  • Xero’s refresh tokens are single use meaning that you will receive a new refresh token after every refresh. You should replace your existing refresh token with the new one each time.
  • To make the offline connection more resilient we allow used refresh tokens to be retried for a grace period of 30 minutes (after first use). We recommend building retry functionality into your integration in case you don’t receive the new token after a refresh.
  • Unused refresh tokens expire after 60 days at which point the user will need to reauthorise your app. If it’s likely that your integration will be inactive for more than sixty days you may want to set up a scheduled refresh at least every 60 days to ensure the connection stays alive.

If you follow these steps it should be pretty straightforward to get you machine to machine style integration up and running and for it to run seamlessly in the background without user interaction.