Skip to content

Update scopes.md #1832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tfordcodat merged 5 commits into from
May 20, 2026
Merged

Update scopes.md #1832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d93989f
Update scopes.md
tfordcodat May 20, 2026
f13415d
Reformat Xero scopes table
pmckinney-codat May 20, 2026
d53d022
Add frontmatter and tweak wording in Xero scopes doc
pmckinney-codat May 20, 2026
11d59fc
Fix multi-entity update link in two Portal blog posts
pmckinney-codat May 20, 2026
5d43e7b
Update scopes.md
tfordcodat May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion blog/260430-portal-subsidiaries-page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ We are introducing the following improvements:
- Dedicated subsidiaries table reuses the familiar Companies table, including search, sort, connection-status filter, and infinite scroll.
- Edit, delete, and link actions are available directly from each subsidiary row, matching the behavior on the top-level Companies page.

These improvements apply to all parent companies in the Portal and complement the [hierarchical company table](/blog/multi-entity-portal-update) we shipped earlier this year.
These improvements apply to all parent companies in the Portal and complement the [hierarchical company table](/updates/260217-multi-entity-portal-update) we shipped earlier this year.

## Who is this relevant for?

Expand Down
2 changes: 1 addition & 1 deletion blog/260506-always-visible-search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ We are introducing the following improvements:
- Focusing the empty search input opens a popover that lists exactly which fields you can search by: **Company ID**, **Company name**, **Connection ID**, **Connected platform**, and **User who created it**.
- An updated placeholder ("Search company, platform, ID...") makes the supported search terms clearer at a glance.

These improvements apply to the Companies and Subsidiaries pages and build on the [multi-entity company table](/blog/multi-entity-portal-update) we shipped earlier this year.
These improvements apply to the Companies and Subsidiaries pages and build on the [multi-entity company table](/updates/260217-multi-entity-portal-update) we shipped earlier this year.

## Who is this relevant for?

Expand Down
46 changes: 32 additions & 14 deletions docs/integrations/accounting/xero/partner-certification/scopes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,43 @@
---
title: "Xero scopes by use case"
description: "Detailed guidance on access scopes required for the Xero partnership certification"
description: "Detailed guidance on the new granular access scopes required for the Xero partnership certification"
---

[Checkpoint 7: Scopes](https://developer.xero.com/documentation/xero-app-store/app-partner-guides/certification-checkpoints/#required-for-all-integrations), part of the Xero App Partner certification program, requires that apps have the minimal access to data as required by their use case.
[Checkpoint 5: Scopes](https://developer.xero.com/documentation/xero-app-store/app-partner-guides/certification-checkpoints/#required-for-all-integrations), part of the Xero App Partner certification program, requires that apps have the minimal access to data as required by their use case.
Copy link
Copy Markdown

@github-actions github-actions Bot May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[Google.Colons] ': S' should be in lowercase.


To comply, you must define the access scopes you need for your intended use case. During the app review, Xero will ask you to justify your use of scopes and explain why you are accessing the related data.

We have mapped out the Xero scopes that apply to each specific Codat use case in the table below. You will also need these scope regardless of the use case:
We have mapped out the Xero scopes that apply to each specific Codat use case in the table below. You will also need these scopes regardless of the use case:
Comment thread
pmckinney-codat marked this conversation as resolved.
Comment thread
pmckinney-codat marked this conversation as resolved.

- `offline_access`
- `accounting.settings`

| **Xero Partnership Type** | **Codat Use Case** | **Suggested Xero Scopes** |
| --------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Financial Services - Bank Feeds | Reconciling bank transactions | `bankfeeds` |
| Financial Services - Lending | Lending - Loan qualification | `accounting.reports.read` <br/> `accounting.transactions`<br/>`accounting.contacts` <br/> `accounting.attachments`<br/>`accounting.reports.bankstatement.read` |
| Financial Services - Lending | Lending - Invoice finance | `accounting.reports.read` <br/> `accounting.transactions` <br/> `accounting.contacts` <br/> `accounting.attachments`<br/>`accounting.reports.bankstatement.read` |
| App Store and Financial Services - Bank Feeds | Managing expenses | `accounting.transactions` <br/> `accounting.contacts` <br/> `accounting.attachments` <br/> `bankfeeds` |
| App Store | Dashboarding | Read-only configuration required. Please work with your implementation specialist to configure scopes. |
| App Store | Automating payables | `accounting.transactions` <br/> `accounting.contacts` <br/> `accounting.attachments` |
| App Store | Automating receivables | `accounting.transactions` <br/> `accounting.contacts` <br/> `accounting.attachments` |
| App Store | Integrating commerce data | `accounting.journals.read` <br/> `accounting.transactions` <br/> `accounting.contacts` |
| App Store | Managing payroll | `accounting.journals.read` <br/> `accounting.transactions` |
## About Xero's granular scopes

Xero is replacing its broad OAuth 2.0 scopes — most notably `accounting.transactions` — with a set of more granular scopes, so your app requests only the data it needs.
Comment thread
pmckinney-codat marked this conversation as resolved.
Comment thread
pmckinney-codat marked this conversation as resolved.

If you create a new Xero app on or after **March 2, 2026**, you must use the new granular scopes from day one. If your app already exists, you can begin requesting the granular scopes from **April 2026**, and you must complete your migration by **September 2027**.

Granular scopes aren't applied to existing tokens automatically. Because your app is requesting a different set of permissions, each customer connection requires fresh, explicit consent, and you'll need customers to reauthenticate with the granular apps.

For full details, see Xero's [Granular Scopes FAQs](https://developer.xero.com/faq/granular-scopes) and the announcement post, [Upcoming changes to Xero accounting API scopes](https://devblog.xero.com/upcoming-changes-to-xero-accounting-api-scopes-705c5a9621a0).

## Scopes by Codat use case

| Xero Partnership Type | Codat Use Case | Current (broad) Xero Scopes | New granular Xero scopes |
Comment thread
pmckinney-codat marked this conversation as resolved.
| --------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Financial Services - Bank Feeds | Reconciling bank transactions | `bankfeeds` | `bankfeeds` |
| Financial Services - Lending | Lending - Loan qualification | `accounting.reports.read`<br/>`accounting.transactions`<br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`accounting.reports.bankstatement.read` | `accounting.invoices`<br/>`accounting.payments` <br/>`accounting.banktransactions` <br/>`accounting.reports.balancesheets.read` <br/>`accounting.reports.profitandloss.read`<br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`accounting.reports.banksummary.read` |
| Financial Services - Lending | Lending - Invoice finance | `accounting.reports.read`<br/>`accounting.transactions`<br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`accounting.reports.bankstatement.read` | `accounting.invoices` <br/>`accounting.payments`<br/>`accounting.banktransactions` <br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`accounting.reports.balancesheets.read` |
| App Store and Financial Services - Bank Feeds | Managing expenses | `accounting.transactions`<br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`bankfeeds` | `accounting.banktransactions`<br/>`accounting.contacts`<br/>`accounting.attachments`<br/>`bankfeeds` |
| App Store | Dashboarding | Read-only configuration required. Please work with your implementation specialist to configure scopes. | Read-only configuration required. Please work with your implementation specialist to configure scopes. |
| App Store | Automating payables | `accounting.transactions`<br/>`accounting.contacts`<br/>`accounting.attachments` | `accounting.invoices`<br/>`accounting.payments`<br/>`accounting.banktransactions`<br/>`accounting.contacts`<br/>`accounting.attachments` |
| App Store | Automating receivables | `accounting.transactions`<br/>`accounting.contacts`<br/>`accounting.attachments` | `accounting.invoices`<br/>`accounting.payments`<br/>`accounting.contacts`<br/>`accounting.attachments` |
| App Store | Integrating commerce data | `accounting.journals.read`<br/>`accounting.transactions`<br/>`accounting.contacts` | `accounting.invoices`<br/>`accounting.payments`<br/>`accounting.banktransactions`<br/>`accounting.journals.read` _(needs Advanced tier)_<br/>`accounting.contacts` |
| App Store | Managing payroll | `accounting.journals.read`<br/>`accounting.transactions` | `accounting.manualjournals`<br/>`accounting.journals.read` _(needs Advanced tier)_ |
| App Store and Financial Services | Spend Insights | `accounting.contacts`<br/>`accounting.attachments`<br/>`accounting.transactions` | `accounting.invoices`<br/>`accounting.payments` <br/>`accounting.banktransactions` <br/>`accounting.contacts`<br/>`accounting.attachments` |
| App Store and Financial Services | FX Insights | | `accounting.invoices`<br/>`accounting.payments` <br/>`accounting.banktransactions` <br/>`accounting.contacts`<br/>`accounting.attachments` |

### A note on the Xero Advanced tier

The `accounting.journals.read` scope is only available to apps on Xero's **Advanced** tier. If your use case requires it, confirm your Xero subscription level before submitting for certification.
Loading