Xero Scopes: What Changed and What It Means for Your Integration

Xero has replaced two broad OAuth 2.0 scopes with a set of fine-grained scopes that limit each app to only the specific endpoints it needs. If you created your Xero app on or after March 2, 2026, the old broad scopes are simply not available to you. If your app predates that cutoff, you have until September 2027 to migrate.

This is part of a larger restructuring of the Xero developer platform that also includes new API pricing tiers and premium-gating of the Journals endpoint. The scope changes themselves are a genuine security improvement. But combined with the pricing changes, they create real planning work for any team building on Xero.

What exactly changed

Two broad scopes are being deprecated: accounting.transactions and accounting.reports.read.

Before and after: transaction scopes

Before (deprecated)	After (granular)	Endpoints covered
`accounting.transactions`	`accounting.invoices`	Credit notes, invoices, linked transactions, purchase orders, quotes, repeating invoices, items
`accounting.transactions`	`accounting.payments`	Batch payments, overpayments, payments, prepayments
`accounting.transactions`	`accounting.banktransactions`	Bank transactions, bank transfers
`accounting.transactions`	`accounting.manualjournals`	Manual journals
`accounting.transactions`	`accounting.classicexpenses`	Expense claims, receipts (deprecated endpoint)

Each granular scope also has a .read variant for read-only access. So if your app only needs to pull invoice data without writing, you request accounting.invoices.read instead of the full scope.

One detail worth noting: the items endpoint is available via both the accounting.invoices and accounting.settings scopes. If your app only works with items and not invoices, you do not need the invoices scope.

Before and after: report scopes

Before (deprecated)	After (granular)	Reports covered
`accounting.reports.read`	`accounting.reports.aged.read`	Aged Payables by Contact, Aged Receivables by Contact
`accounting.reports.read`	`accounting.reports.balancesheets.read`	Balance Sheet
`accounting.reports.read`	`accounting.reports.banksummary.read`	Bank Summary
`accounting.reports.read`	`accounting.reports.executivesummary.read`	Executive Summary
`accounting.reports.read`	`accounting.reports.profitandloss.read`	Profit and Loss
`accounting.reports.read`	`accounting.reports.trialbalance.read`	Trial Balance
`accounting.reports.read`	`accounting.reports.taxreports.read`	GST and BAS reports

Scopes that are not changing

accounting.contacts, accounting.settings, accounting.attachments, and accounting.budgets remain available to every app regardless of when it was created. Non-Accounting API scopes like Payroll, Files, Assets, Projects, and the Finance API are also unaffected.

The two-track timeline

This is the most important detail for development teams to understand.

Apps created before March 2, 2026 can continue using the broad accounting.transactions and accounting.reports.read scopes until September 2027. During the transition, these apps can use a mix of broad and granular scopes simultaneously. Scopes are additive, so a user who re-authorizes receives both the legacy and new scope grants on their token.

By end of April 2026, Xero will assign the new granular scopes to all existing apps in the developer portal. But these will not automatically propagate to existing tokens. You need to update your authorization URL to request the granular scopes, and each connected user must re-authorize to receive the new permissions. There is no silent migration path. Explicit user consent is required for every connection.

Apps created on or after March 2, 2026 have no access to the broad scopes at all. Their authorization links must specify only granular scopes from day one. If a new app calls an endpoint without the matching granular scope, the API returns HTTP 401 Forbidden with an insufficient_scope error. If you are setting up a Xero app for the first time, you will only see the new granular scopes in the developer portal.

Journals, manual journals, and bank feeds: three different things

This is where the changes get most confusing, because three closely related concepts are governed by entirely different access regimes.

Manual journals (the /api.xro/2.0/ManualJournals endpoint) remain available at all pricing tiers under the new accounting.manualjournals granular scope. This endpoint handles user-created journal entries and is not restricted beyond requiring the correct scope.

The Journals endpoint (/api.xro/2.0/Journals) returns system-generated double-entry journal lines for every transaction in the ledger. This endpoint is now a premium feature gated behind the Advanced pricing tier, which starts at $1,445 AUD per month. Access requires both a security assessment and explicit use-case approval from Xero. If your integration depends on full ledger reconciliation or audit trail functionality, this is the endpoint that matters, and it now comes with a significant cost.

Bank feeds operate under their own separate API and scope (bankfeeds), which is not affected by the accounting scope changes at all. The Bank Feeds API has its own certification requirement and separate contractual terms. If your app only pushes bank statement data into Xero, the accounting.transactions deprecation does not impact you.

Bank transactions, meaning the read and write endpoints for reconciled bank line items within Xero's ledger, move from the old broad scope to accounting.banktransactions. This is distinct from bank feeds. Bank feeds push raw statement data in. Bank transactions are the resulting accounting records inside Xero.

What you need to do

If you have an existing Xero integration, the migration path follows a few steps.

Update your authorization URL to replace the broad scopes with the specific granular scopes your app actually needs. Only request the scopes you use. Requesting everything defeats the purpose and will make users hesitant to authorize.

Let new users authorize with the new scopes naturally. For existing connected users, let re-authorization happen organically when users add new organizations or refresh their connection. The additive scope behavior means users accumulate both scope sets during the transition.

Before September 2027, migrate any remaining connections that still only have broad scopes. For holdouts, you can force re-authorization by removing their connection via the API, which requires them to reconnect with the new scopes.

For testing, create a new app in the Xero developer portal. It will default to granular scopes and can be tested against a Demo Company. No SDK changes are needed since the scopes operate at the OAuth authorization layer.

If you are building a new integration from scratch, you start with granular scopes by default. Plan your scope requests carefully based on which endpoints you actually need.

If you are using Apideck to connect to Xero, you can configure which scopes your app requests in the Apideck dashboard. Our Xero connector setup guide walks through entering your OAuth credentials and reviewing the scopes granted in Xero against the scopes you are requesting in Apideck.

The bigger picture

The granular scope change fulfills a long-standing feature request on Xero's UserVoice forum, where developers have been asking for finer-grained permissions since at least 2010. For years, requesting invoice access also exposed bank balances and salary data because there was only one broad scope covering all of it. Fine-grained permissions are a real improvement.

But the timing is not great. Xero bundled this change with connection-based pricing tiers and premium-gating of key endpoints like Journals. For developers who have been building on the platform for years with free API access, the combined effect feels like a significant shift in the economics of building on Xero.

This is part of a broader pattern across accounting platforms. As we covered in our overview of accounting API pricing and partnerships, every major provider is evolving its developer program in a direction that adds cost and complexity. QuickBooks has its own partnership requirements. Sage remains free but has a smaller market footprint. NetSuite charges separately through its SuiteCloud licensing.

For teams building accounting integrations that need to support multiple platforms, the platform-specific scope and pricing changes reinforce the case for abstracting away provider differences. Whether you build direct integrations or use a unified API layer, the goal is the same: insulate your product from the policy changes of any single platform.