Why did this work on our old Xero app?

Apps created before March 2026 kept the broad scopes. A new app, or a re-registered one, is granted granular scopes only.

Which user should connect Xero?

An adviser-level user, or a standard user with the permissions matching every scope requested. A user missing one permission fails the whole consent.

Will the agent lose access when that person leaves?

The refresh token belongs to the app and the organisation, not the person, but Xero revokes it if the connecting user is removed. Reconnect with a service account or a remaining adviser before the departure.

Does KYN need write access to our ledger?

Only for drafts: bills, invoices and journals are created as drafts and a person approves them in Xero. Read scopes cover the rest.

Fix · Finance

Xero returns invalid_scope on accounting.transactions.

The OAuth consent screen or the token call returns "invalid_scope" when the app asks for accounting.transactions, accounting.settings or accounting.contacts, on an app created in 2026.

Cause.

Xero stopped granting the broad legacy scopes to apps created after March 2026. New apps must request the granular scopes (for example accounting.transactions.read, accounting.invoices, accounting.manualjournals, accounting.contacts.read) and the connecting user must be an adviser or standard user with the matching permission.

Fix.

01	Open the app in the Xero developer portal and list the scopes it requests.
02	Replace each legacy scope with the granular scopes the agent needs: read scopes for what it reads, write scopes only for what it drafts.
03	Reconnect the organisation with an adviser-level user; the consent screen must list every scope requested.
04	Store the refresh token in the cloud secret store, not in configuration.
05	Run the dry run against a closed month and compare the row counts before any live posting.

How the build avoids it.

KYN’s finance agents request granular scopes from the first connection and record the scope list in the runbook, so a reconnect after a staff change asks for exactly the same set.

Xero integration →Finance agents →Every finance article →

Checked 13 October 2026 against a live build. Vendors change behaviour; if a step no longer matches, tell us and the page changes.

Questions operators ask

Why did this work on our old Xero app?: Apps created before March 2026 kept the broad scopes. A new app, or a re-registered one, is granted granular scopes only.
Which user should connect Xero?: An adviser-level user, or a standard user with the permissions matching every scope requested. A user missing one permission fails the whole consent.
Will the agent lose access when that person leaves?: The refresh token belongs to the app and the organisation, not the person, but Xero revokes it if the connecting user is removed. Reconnect with a service account or a remaining adviser before the departure.
Does KYN need write access to our ledger?: Only for drafts: bills, invoices and journals are created as drafts and a person approves them in Xero. Read scopes cover the rest.