Important Notice

OAuth 1.0a support for public and partner apps ended 31 March 2021

All partner and public apps should have migrated to OAuth 2.0 and we are now removing OAuth 1.0a support. If your public or partner app is still using OAuth 1.0a, this means you’ll no longer be able to make API requests and your customers won’t be able to sync their data with Xero.

If you haven’t migrated to your public or partner OAuth 1.0a app to OAuth 2.0, you will need to contact us ASAP to arrange a short extension.

Public apps: contact our developer platform support team.
Partner apps: please reach out to your app partner manager or developer evangelist in the first instance. Otherwise, contact our developer platform support team.

Key dates for migrating OAuth 1.0a apps to OAuth 2.0

Early December 2019: no new OAuth 1.0a apps created.
Mid December 2019: OAuth 2.0 migration endpoint available to partner apps.
31 March 2021: All certified partner apps required to be on OAuth 2.0.
31 March 2021: All public apps required to be on OAuth 2.0.
31 March 2021: OAuth 1.0a will no longer be supported for public and partner apps.
30 September 2021: OAuth 1.0a will no longer be supported for private apps.

OAuth 2.0

OAuth 2.0 is a protocol that lets your app access a user's account without accessing their password. Your app requests specific permission scopes and is granted an access token upon a user's approval.

Xero OAuth 2.0 fundamentals

As part of the OAuth flow, a user will connect your app to one or more tenants. Depending on the API you're using, a tenant can be a Xero organisation, a Xero HQ practice, a Xero Practice Manager account or a WorkflowMax account.
A newly created app can connect to a maximum of 25 tenants. To connect to more than 25 tenants you need to get your app certified.
All apps have the ability to maintain offline conections. To establish an offline connection simply request the offline_access scope during authorization.

Choose the right authorization flow for your app

Xero’s API supports the authorization code grant type using the standard authorization code flow or the Proof Key for Code Exchange (PKCE) extension.

The standard flow is the most well known OAuth 2.0 flow and typically used by web server applications. It requires your app to securely use and store a client secret.

The PKCE flow requires your app to create a secret (called a code verifier) for each authorization request. It’s slightly more complicated to implement but offers a secure way to connect to the API if your app can’t be trusted to store a client secret. Native (desktop and mobile) apps are required to use PKCE if connecting directly to the API. Support for Single Page Apps (SPAs) is coming soon.

Migrating from OAuth 1.0a

We have a migration endpoint for partner apps to bring existing connections to OAuth2.0. Migrating your connections will provide a smoother user experience and ensure your app retains its status in the partner program.

We will not be providing a migration path for public and private apps. If you have an integration using a public or private app you can create a new OAuth2.0 app and migrate your users at any time.

Authorising integrations with no user interface

Wondering how OAuth 2.0 can work for your back-end service/script? Check out our guide for building integrations with no UI using OAuth 2.0.

Questions?

If you have and questions then check out our FAQs on OAuth 2.0 and the migration. If you still need more information then contact us the usual way.

SDKs

We have a range of new SDKs and sample apps that integrate with OAuth 2.0. These are all generated from our collection of OpenAPI definitions.