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.
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
Bank Feeds
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 |