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, Quotes, Payments, Prepayments, PurchaseOrders, Receipts, RepeatingInvoices
accounting.transactions.read	View your business transactions	As above but GET only
accounting.reports.read	View your reports	AgedPayablesByContact, AgedReceivablesByContact, BalanceSheet, BankSummary, BASReport, BudgetSummary, ExecutiveSummary, GSTReport, ProfitAndLoss, TrialBalance
accounting.reports.tenninetynine.read	View your 1099 reports	1099Report
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

Budgets

accounting.budgets.read View your budgets Budgets

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	Access to all endpoints on the WorkflowMax API
workflowmax.read	View your WorkflowMax data	As above but GET only
workflowmax.job	View and manage your WorkflowMax job data	Access to job endpoints
workflowmax.job.read	View your WorkflowMax job data	As above but GET only
workflowmax.client	View and manage your WorkflowMax client data	Access to client and client group endpoints
workflowmax.client.read	View your WorkflowMax client data	As above but GET only
workflowmax.staff	View and manage your WorkflowMax staff data	Access to staff endpoints
workflowmax.staff.read	View your WorkflowMax staff data	As above but GET only
workflowmax.time	View and manage your WorkflowMax time data	Access to time endpoints
workflowmax.time.read	View your WorkflowMax time 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	Access to all endpoints on the Practice Manager API
practicemanager.read	View your Practice Manager data	As above but GET only
practicemanager.job	View and manage your Practice Manager job data	Access to job endpoints
practicemanager.job.read	View your Practice Manager job data	As above but GET only
practicemanager.client	View and manage your Practice Manager client data	Access to client endpoints and client group endpoints
practicemanager.client.read	View your Practice Manager client data	As above but GET only
practicemanager.staff	View and manage your Practice Manager staff data	Access to staff endpoints
practicemanager.staff.read	View your Practice Manager staff data	As above but GET only
practicemanager.time	View and manage your Practice Manager time data	Access to time endpoints
practicemanager.time.read	View your Practice Manager time data	As above but GET only

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