Scopes

When your app is requesting authorisation from a user it will need to ask for a set of scopes. These scopes will be displayed to the user and describe what data your app will be able to access.

Scopes are additive

You should request the minimum scopes required for whatever action that user is performing. For example, if a user is doing single sign on you should only request the OpenID scopes. Later, if they want to connect to their Xero organisation you can request the additional scopes (e.g. accounting.transactions) by sending them through the OAuth flow again. Each subsequent time your app sends a user through the flow, any new scopes will be added to previously consented scopes.

It's not possible to remove scopes from an existing access token. The only way to reduce consented scopes is to revoke the token and start again.

Offline access

To get a refresh token, you must request the offline_access scope. A refresh token allows you to refresh your access token and maintain an offline connection.

offline_access

User scopes

OpenID Connect

Use OpenID scopes to retrieve details about the user's identity. These are required for single sign on.

openid	your application intends to use the user's identity
profile	first name, last name and xero user id
email	email address

Organisation scopes

Request these scopes if your app needs to access data in a Xero Organisation

Accounting API

accounting.transactions	View and manage your business transactions	BankTransactions, BankTransfers, BatchPayments, CreditNotes, ExpenseClaims, Invoices, LinkedTransactions, ManualJournals, Overpayments, Payments, Prepayments, PurchaseOrders, Receipts, RepeatingInvoices
accounting.transactions.read	View your business transactions	As above but GET only
accounting.reports.read	View your reports	1099Report, AgedPayablesByContact, AgedReceivablesByContact, BalanceSheet, BankSummary, BASReport, BudgetSummary, ExecutiveSummary, GSTReport, ProfitAndLoss, TrialBalance
accounting.journals.read	View your general ledger	Journals
accounting.settings	View and manage your organisation settings	Accounts, BrandingThemes, Currencies, Employees, Items, InvoiceReminders, Organisation, TaxRates, TrackingCategories, Users
accounting.settings.read	View your organisation settings	As above but GET only
accounting.contacts	View and manage your contacts	Contacts, ContactGroups
accounting.contacts.read	View your contacts	As above but GET only
accounting.attachments	View and manage your attachments	Attachments
accounting.attachments.read	View your attachments	As above but GET only

Payroll API Australia

payroll.employees	View and manage your employees	Employees, LeaveApplications
payroll.employees.read	View your employees	As above but GET only
payroll.payruns	View and manage your pay runs	Payruns
payroll.payruns.read	View your pay runs	As above but GET only
payroll.payslip	View and manage your payslips	Payslips
payroll.payslip.read	View your payslips	As above but GET only
payroll.timesheets	View and manage your timesheets	Timesheets
payroll.timesheets.read	View your timesheets	As above but GET only
payroll.settings	View and manage your payroll settings	Settings, PayrollCalendars, PayItems, SuperFunds, SuperFundProducts
payroll.settings.read	View your payroll settings	As above but GET only

Payroll API UK

payroll.employees	View and manage your employees	Employees, Employment, Leave, Leave Balances, Statutory Leave Balances, Statutory Leave Summary, Statutory Sick Leave, Payment Methods, Salary and Wages, Opening Balances, Leave Periods, Leave Types, Employee Pay Templates
payroll.employees.read	View your employees	As above but GET only
payroll.payruns	View and manage your pay runs	Payruns
payroll.payruns.read	View your pay runs	As above but GET only
payroll.payslip	View and manage your payslips	Payslips
payroll.payslip.read	View your payslips	As above but GET only
payroll.timesheets	View and manage your timesheets	Timesheets
payroll.timesheets.read	View your timesheets	As above but GET only
payroll.settings	View and manage your payroll settings	Settings, Payrun Calendars, Tracking Categories, Earning Rates, Deductions, Leave Types, Reimbursements, Earnings Orders, Employer Pensions
payroll.settings.read	View your payroll settings	As above but GET only

Payroll API New Zealand

payroll.employees	View and manage your employees	Employees, Employment, Tax, Leave, Leave Setup, Leave Balances Payment Methods, Salary and Wages, Opening Balances, Leave Periods, Leave Types, Employee Pay Templates
payroll.employees.read	View your employees	As above but GET only
payroll.payruns	View and manage your pay runs	Payruns
payroll.payruns.read	View your pay runs	As above but GET only
payroll.payslip	View and manage your payslips	Payslips
payroll.payslip.read	View your payslips	As above but GET only
payroll.timesheets	View and manage your timesheets	Timesheets
payroll.timesheets.read	View your timesheets	As above but GET only
payroll.settings	View and manage your payroll settings	Settings, Payrun Calendars, Tracking Categories, Earning Rates, Deductions, Leave Types, Reimbursements, Statutory Deductions
payroll.settings.read	View your payroll settings	As above but GET only

Files API

files	View and manage your file library	Files, Folders, Associations
files.read	View your file library	As above but GET only

Assets API

assets	View and manage your fixed assets	Assets, Folders, Settings
assets.read	View your fixed assets	As above but GET only

Projects API

projects	View and manage your projects	Projects, Tasks, Time
projects.read	View your projects	As above but GET only

The following scopes are only available after additional certification. If you require access to these scopes please let us know once you register to be a partner. Additional commercial agreements may apply.

Payment Services

paymentservices View and manage your payment services PaymentServices

Bank Feeds

bankfeeds View and manage your bank statements FeedConnections, Statements

WorkflowMax scopes

Request these scopes if your app needs to access data in a WorkflowMax account

WorkflowMax API

workflowmax	View and manage your WorkflowMax data	All endpoints on the WorkflowMax API
workflowmax.read	View your WorkflowMax data	As above but GET only

Practice Manager account scopes

Request these scopes if your app needs to access data in a Practice Manager account

To access the Practice Manager API you will need to first register as an app partner and complete a security self-assessment questionnaire. Your app won't be able to request Practice Manager scopes until you've started this process.

Practice Manager API

practicemanager	View and manage your Practice Manager data	All endpoints on the Practice Manager API
practicemanager.read	View your Practice Manager data	As above but GET only/td>

Xero HQ practice scopes

Request these scopes if your app needs to access data in a XeroHQ practice

XeroHQ API

XeroHQ scopes will only available after additional certification. If you require access to these scopes please let us know when you register to be a partner.

Coming soon!