An update on why we are saying goodbye OAuth 1.0a, hello OAuth 2.0

You’ve likely heard a little bit about us migrating from OAuth 1.0a to OAuth2.0. It’s a big move, but worth it.

OAuth is the authentication process Xero uses to grant third-party developers secure access to Xero customers’ data, via the API, without sharing their Xero password. Today we use OAuth 1.0a, but to better serve our entire community, we’re moving to the industry standard, OAuth 2.0.

OAuth 2.0 improves the way third parties connect to Xero’s API, making it easier to innovate with us and help solve more problems for our shared customers — now and in the future.

We want to make the transition to OAuth 2.0 as smooth as possible. So this blog outlines what’s so great about OAuth 2.0, what you can expect by when, and what you need to know depending on how you use our API.

Why OAuth 2.0? It helps everyone thrive

From developers and app partners, to small businesses, banks and advisors, OAuth 2.0 improves the experience for everyone and makes it easier for businesses to connect with apps, advisors, and financial institutions. This is because it:

• Is highly secure and meets the API industry standard
• Provides a smoother path to certification
• Unlocks App Partner Programme benefits
• Enables Sign in with Xero
• Ensures we meet regulatory requirements in all regions
• Makes it quick and easy to get set up and innovate
• Provides a clear, informed consent experience for customers

Key dates

• Feb — June 2020
  Ruby, PHP, .Net, Java and Node SDK enhancements based on early feedback and use.
• 30 April 2020
  Python SDK and PKCE delivered. (Update: read our update on PKCE here. Update 2: The Python SDK and Sample App are now available)
• December 2020
  All app partners and accounting and bookkeeping partners migrated.
• March 2021
  Full deprecation of OAuth 1.0a.

What you need to know depending on how you use our API:

Partner apps

• Migration guide: The migration endpoint and guide and FAQs are now available for all partner apps and the sample .Net example is on GitHub.
• Feedback and benefits: It took our first partner around two weeks to migrate. Migrating your connections will provide a smoother user-experience and ensure your app retains its status in Xero’s app partner programme. So we recommend getting this on your roadmap asap.

Accountants and bookkeepers

• Xero Marketplace apps: Our partner apps have a seamless migration path that shouldn’t affect you or your clients. If you have any questions about their migration, please reach out to the app’s support team first.
• Custom integrations (Private apps): If you have a bespoke API integration to access your client’s Xero data you’ll need to move to OAuth 2.0 and will no longer be able to create a new private app when onboarding clients. Please see the “Private app” section below and get in touch if you need a temporary solution until June 2020.

App users

• Xero Marketplace apps: Our Partner apps have a seamless migration path that shouldn’t affect you. If you have any questions about their migration, please reach out to the app’s support team first.
• Custom integrations (Private apps): If you have an app connected to your Xero organisation that isn’t from the Xero marketplace (e.g. a custom built integration) it will need to be upgraded to use OAuth 2.0 by the end of the year. If you need a developer we have a great selection of custom integrators listed on our marketplace.

Private apps

• We still encourage you to build custom integrations: Unlike OAuth1.0a, you no longer need to decide between offline access, multiple organisation connections and certification. Generating and uploading an x509 certificate is no longer required. Just grab your favourite OAuth 2.0 library and start building.
• Desktop apps: We’re prioritising PKCE and are aiming to deliver this in April 2020. We’ll keep you updated on progress. (Update: PKCE is now available, read about PKCE here.)
• Machine to machine (M2M): Because all our OAuth 2.0 apps allow offline access to be granted, it’s possible to set up M2M-style integrations. Only the initial authorization code flow needs to be done with a user and the web browser.
  While this creates an extra step for you as a developer, it ensures our (mostly non-technical) users always get a familiar and consistent way of granting access to their Xero data. They don’t need to give you a login to their Xero organisation or get stuck trying to generate and upload a x509 certificate.
  We understand there’s use cases where developers are accessing their own data, and that OAuth 2.0 means extra steps and work on your end. This is a trade-off we’ve decided to make based on our user base as a whole. We’re committed to supporting you through this process and are actively investigating potential options to improve the experience. For now, please reach out so we can work with you directly.
• Refresh tokens: Once you have the refresh token, no further user interaction is required. As long as you perform a refresh at least every 30 days, the connection will be maintained.
  We’ve had some good community feedback that 30 days isn’t long enough for monthly jobs so we’ll be extending the refresh token lifetime to 60 days in the very near future. We’ve also recently added a grace period to used refresh tokens, meaning you can retry a token refresh that fails. This makes the offline connection far more robust.
• Connecting your app: Once you’ve created your new OAuth 2.0 app, you or your customers will need to connect it to your Xero organisation.
  If you’re a developer building an integration for yourself it could be as easy as using Postman to step through the flow to get a refresh token for your org. If you’re building an app for clients, it might be worth building a simple web app to navigate the flow. You could easily re-purpose one of our sample apps or any basic web app that handles an OAuth 2.0 authorization flow.
• Any other questions: Please get in touch.

Why we’ve made these changes

No long-lived access tokens
In the interests of keeping customers data secure we won’t be supporting long-lived access tokens in OAuth 2.0. OAuth 1.0a had the additional protection of a private key that was used to generate the signature in addition to the access token. OAuth 2.0 only requires the access token to make calls. This makes development far simpler but also makes access tokens far more sensitive than they were previously. Short lived tokens are one way that we can still maintain a high level of security with OAuth 2.0.

Discontinuing “private apps” — enhanced transparency and privacy

At Xero, we have a duty of care to protect the data and privacy of our community. We’re always looking at ways to improve security and have been working closely with the Australian Tax Office and other industry players around raising security best practice. You can read more about our new security standards here.

Xero’s subscribers are predominantly accounting partners and small business owners. It’s critical they know exactly which apps are connecting to their financial data and what data is being shared.

We’ve chosen to only support the code grant type because it’s the most suitable for our API access model. All our APIs require an app to act on behalf of a user so it’s imperative users (resource owners) explicitly grant consent to those apps as part of an authorization flow.

The great thing about OAuth2.0 is many of the workarounds that private apps faced with OAuth1 no longer exist. For example, if you needed offline access or to connect to multiple Xero organisations, the only solution in OAuth1.0a was to create multiple private apps. However, this is no longer a restriction in OAuth 2.0. We’re allowing all apps to maintain offline access and to connect to multiple (up to 25) organisations.

We’ve removed the ability to create new OAuth1.0a apps to limit the number of apps that would eventually need to be migrated. However, we’ll continue to support existing developers who need to create new private apps until the end of June 2020. If this is you, please get in touch.

We’re not supporting the client credentials grant type

The client credentials grant type is intended for apps that act on behalf of themselves. None of our APIs currently work that way. All of our APIs require an app to act on behalf of a user, which aligns best with the authorization code grant.

We’re owning and supporting more SDKs

With OAuth 2.0, we now have official SDKs for Ruby and PHP in addition to .Net, Java and Node. Python is coming soon, along with support for more of the non-accounting endpoints. If you’re waiting for Python or a particular API (e.g. Payroll) to be supported in OAuth 2.0, please get in touch and we’ll ensure you’re able to continue creating new private apps in OAuth 1.0a in the interim. (Update: Python is now available)

It will take time before these new SDKS are as functional and battle-hardened as our existing ones, but having our community use them will help us get there. Thanks for all of the feedback and pull requests we’ve received already.

How to keep informed going forward

• Monthly updates: We always share any important information in our developer newsletter. If you’re not already a subscriber, update your developer profile.
• Developer center: Check out the OAuth 2.0 overview and make sure you’re familiar with the FAQs. We’ll update these with anything new when appropriate.
• Direct emails from us: Depending on your use case, you may receive direct emails from us during the course of the migration. Please make sure your details are up to date and the right people in your business are reading all communications from Xero and api@xero.com.