Developer documentation

Scopes

Xero's own scope strings, used unchanged, and how a key's grant is narrowed by the connection.

How scoping works

A key's effective permission on an organisation is the intersection of the scopes granted to the key and the scopes the underlying Xero connection currently holds.

effective = key.scopes ∩ connection.grantedScopes

Re-authorising a connection with fewer scopes therefore narrows every key on it rather than breaking them with a Xero-side error. Read-only variants are distinct grants: accounting.transactions.read never permits a write.

Scope reference

Accounting

Scope	Access	What it grants
accounting.transactions	read and write	Create and update invoices, bills, credit notes and payments
accounting.transactions.read	read only	Read invoices, bills, credit notes and payments
accounting.contacts	read and write	Create and update contacts and contact groups
accounting.contacts.read	read only	Read contacts and contact groups
accounting.settings	read and write	Create and update accounts, tax rates, tracking categories and organisation settings
accounting.settings.read	read only	Read chart of accounts, tax rates and organisation settings
accounting.reports.read	read only	Read accounting reports such as Balance Sheet and Profit & Loss
accounting.reports.tenninetynine.read	read only	Read the 1099 report
accounting.journals.read	read only	Read the general ledger journals feed
accounting.attachments	read and write	Upload and replace attachments on accounting records
accounting.attachments.read	read only	Download attachments on accounting records
accounting.budgets.read	read only	Read budgets

Payroll AU

Scope	Access	What it grants
payroll.employees	read and write	Create and update Australian payroll employees
payroll.employees.read	read only	Read Australian payroll employees
payroll.payruns	read and write	Create and update Australian pay runs and pay slips
payroll.payruns.read	read only	Read Australian pay runs and pay slips
payroll.payslip	read and write	Update Australian pay slips
payroll.payslip.read	read only	Read Australian pay slips
payroll.timesheets	read and write	Create and update Australian timesheets
payroll.timesheets.read	read only	Read Australian timesheets
payroll.settings	read and write	Update Australian payroll settings and calendars
payroll.settings.read	read only	Read Australian payroll settings and calendars
payroll.superfunds	read and write	Create and update superannuation funds
payroll.superfunds.read	read only	Read superannuation funds
payroll.superfundproducts.read	read only	Read the superannuation fund product register

Payroll UK

Scope	Access	What it grants
payroll_uk.employees	read and write	Create and update UK payroll employees
payroll_uk.employees.read	read only	Read UK payroll employees
payroll_uk.payruns	read and write	Create and update UK pay runs
payroll_uk.payruns.read	read only	Read UK pay runs
payroll_uk.payslip	read and write	Update UK pay slips
payroll_uk.payslip.read	read only	Read UK pay slips
payroll_uk.timesheets	read and write	Create and update UK timesheets
payroll_uk.timesheets.read	read only	Read UK timesheets
payroll_uk.settings	read and write	Update UK payroll settings
payroll_uk.settings.read	read only	Read UK payroll settings

Payroll NZ

Scope	Access	What it grants
payroll_nz.employees	read and write	Create and update New Zealand payroll employees
payroll_nz.employees.read	read only	Read New Zealand payroll employees
payroll_nz.payruns	read and write	Create and update New Zealand pay runs
payroll_nz.payruns.read	read only	Read New Zealand pay runs
payroll_nz.payslip	read and write	Update New Zealand pay slips
payroll_nz.payslip.read	read only	Read New Zealand pay slips
payroll_nz.timesheets	read and write	Create and update New Zealand timesheets
payroll_nz.timesheets.read	read only	Read New Zealand timesheets
payroll_nz.settings	read and write	Update New Zealand payroll settings
payroll_nz.settings.read	read only	Read New Zealand payroll settings

Files

Scope	Access	What it grants
files	read and write	Upload, update and delete files and folders
files.read	read only	Read and download files and folders

Assets

Scope	Access	What it grants
assets	read and write	Create and update fixed assets
assets.read	read only	Read fixed assets and asset types

Projects

Scope	Access	What it grants
projects	read and write	Create and update projects, tasks and time entries
projects.read	read only	Read projects, tasks and time entries

Bank Feeds

Scope	Access	What it grants
bankfeeds	read and write	Create bank feed connections and deliver statements

Finance

Scope	Access	What it grants
finance.statements.read	read only	Read bank statements accounting data
finance.accountingactivity.read	read only	Read accounting activity metrics
finance.cashvalidation.read	read only	Read cash validation data
finance.bankstatementsplus.read	read only	Read enriched bank statement data