caret

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.

The key dates for migrating OAuth 1.0a apps:

  • 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 - OAuth 1.0a will no longer be supported for Public and Partner apps.
    Note: we’re extending the deprecation of OAuth 1.0a, for existing private apps only, to 90 days after our new, premium custom integration option is available. We’ll share more here soon.

Migrating from the WorkflowMax API

In April 2020 the WorkflowMax API is coming to api.xero.com and OAuth 2.0. For details on migrating from the WorkflowMax API check out the specific guide for Practice Manager apps.

TLS 1.2 is required for OAuth 2.0

All API communication using OAuth 2.0 requires TLS 1.2 or higher. Any requests using TLS 1.1 or lower will receive a 403 Forbidden response.

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.