caret

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

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, Quotes, 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 Xero HQ practice.

Xero HQ API

Xero HQ 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.

hq.clients.read View your client data Clients, Industry Codes
hq.alerts View and manage your alerts Alerts
hq.alerts.read View your alerts As above but GET only
hq.staff View and manage your staff data Staff
hq.staff.read View your staff data As above but GET only