Granular Scopes FAQs — Xero Developer

Granular Scopes

01. What changes are happening to scopes?

From 2 March 2026:

Apps created before 2 March 2026 will have until September 2027 to move from broad scopes to granular scopes, however, we recommend updating as soon as possible. They’ll be available for you to request from April 2026. Once you start using granular scopes, your app will be able to use a mix of broad and granular scopes until all customers migrate to granular scopes by September 2027.
Apps created on or after 2 March 2026 will use the new granular scopes

02. Why are there changes happening to scopes?

Transitioning to granular scopes enhances security and boosts user confidence. Instead of broad access, your app now requests only the exact permissions it needs. This transparency gives users more control during the OAuth 2.0 flow, making it clear how their data is used. This update is a key part of Xero’s commitment to providing a secure, trustworthy platform for all integrations.

03. How do I see what scopes are changing?

You can find a full list of scopes and their associated endpoints on the Scopes page.

04. What happens if a tenant becomes disconnected, can they only reconnect with a granular scope?

If your app was created before 2 March 2026 and one of your existing users becomes disconnected, they’ll be able to go through the OAuth 2.0 flow from your app and reconnect. You don’t need to make any immediate changes to request granular scopes when they are authorising the connection.

05. Will my application automatically receive the new granular scopes that correspond to the broad scopes it currently uses?

Apps created after 2 March 2026, will automatically have the new granular scopes.

For apps created before 2 March 2026, you’ll be able to request the new granular scopes from April 2026. The granular scopes won't automatically be applied to any existing tokens. So, the granular scope won’t be applied to any new authorisations until they are added to the authorisation link your customers are using and the customer reauthorises your app. We’ve added an FAQ on a suggested migration process to help you with migrating existing connections to the new granular scopes.

06. What would be the suggested migration process to use the new granular scopes with minimum impact for my customers?

Here’s some suggested steps to take:

Update your authorisation link to remove the broad scope and add the appropriate granular scopes. For example you might replace accounting.transactions with accounting.invoices.
As new users authorise their connections the tokens you receive will have the new scopes.
Any user that either re-authorises your app or adds additional organisations will also have the new scopes applied. As scopes are additive they will then have both the broad and granular scopes.
Over time and before September 2027 you will hopefully have organically migrated the majority of your users. This would leave a smaller cohort who you would need to prompt to reauthorise their connection.
If you wish to require a use to reauthorise, you can remove their connection via the API so that when they next use your Xero integration they’ll have to reconnect

The sooner your authorisation link can be updated the more effective this approach will be.

07. Can I silently migrate tenants to granular scopes or will my users need to re-authorize their tenants when I switch scopes?

Because you are requesting a different set of permissions, the user must provide explicit consent for the granular scopes. Your app should be prepared to redirect the user back through the OAuth 2.0 flow.

Frequently asked questions