Skip to main content
You connect Xero once at the MSP level, then turn it on per agent. Neo connects through a Xero custom connection: an app you create for your own organisation, which reaches that one organisation with a client id and secret. You need three values: the connection’s Client ID, its Client Secret, and the Scopes you tick on it.
A custom connection is a paid Xero subscription for your organisation, offered to organisations in Australia, New Zealand, the United Kingdom and the United States. Buy it in Xero under Connected apps, or on Xero’s Custom Connections page, before step 2. A Xero user with the Standard, Advisor or Administrator role and the Connected Apps permission can buy it.

​
1. Create the custom connection

1

Open Xero's developer portal

Go to developer.xero.com, sign in with your Xero login, and open My Apps.
2

Create the app

Select New app, name it so your team recognizes it, for example “Neo Agent”, and choose Custom connection as the integration type.
3

Tick the scopes

Tick the scopes for what your agents will do. To read and report on invoices, tick:
  • accounting.invoices.read: invoices, bills, credit notes, quotes and purchase orders
  • accounting.contacts.read: contacts, which Neo maps to your PSA clients
  • accounting.reports.aged.read: aged receivables and payables
  • accounting.settings.read: items, accounts, tax rates and your organisation’s details
Add accounting.payments.read for payments and accounting.banktransactions.read for bank transactions. For writes, tick the scope without .read (such as accounting.invoices). Payroll, projects, assets and files have their own scopes (payroll.employees, projects, assets, files and their .read forms).
4

Choose the authorising user

Pick the Xero user who will connect your organisation, and save. Xero emails that user a link.

​
2. Authorise your organisation and copy the keys

1

Connect the organisation

The authorising user opens Xero’s email, selects Connect, reviews the scopes and chooses your organisation. Xero emails you when the connection is authorised.
2

Copy the Client ID and generate a secret

In My Apps, open the custom connection. Copy the Client id, then generate a Client secret and copy it. Xero shows the secret once.

​
3. Save the keys in Neo

1

Open Integrations

In the Neo Dashboard, open Integrations → Xero, under Accounting.
2

Enter the values

Paste the Client ID and Client Secret. In Scopes, enter the scopes you ticked on the connection, separated by spaces, for example accounting.invoices.read accounting.contacts.read accounting.reports.aged.read accounting.settings.read. Click Save.Neo asks Xero for a token with these values and scopes before it saves, then checks that the connection reaches your organisation. A wrong id or secret, a scope that is not ticked on the connection, or a connection the authorising user has not connected yet is refused on the spot, with the reason.
When you tick another scope on the connection later, add it to Scopes in Neo and save again: Neo asks Xero for exactly the scopes you saved.

​
4. Turn Xero on per agent

Each agent decides whether it uses Xero and which areas it can touch. Open the agent, go to its Tools & Settings tab, click Accounting, and expand the Xero block.

​
Pick a preset

Read Only

Every everyday area read only. Emails, payroll and bank account details off. The agent reads invoices, bills, contacts, payments and reports, and never changes anything.

Helpdesk

Contacts, Invoices, Bills & Quotes, and Projects & Time read and write, each change with technician approval. Every other everyday area read only. Emails, payroll and bank account details off.

IT Admin

Every writable area read and write, payroll included. Emails to contacts, bank account changes, accounts and journals, organisation settings and pay runs wait on a technician.

Full Automation

Every supported write runs with no approval, emails to contacts, bank account changes and pay runs included.

​
Or set each area by hand

​
Safety controls

  • You set the approvals. Each area has its own approval setting, so an agent can record a payment on its own, or ask a technician first.
  • Emails are their own area. An agent that can write invoices cannot email one to your client unless you turn on Emails to Contacts.
  • Bank accounts are their own area. A write that sets a bank account needs Bank Account Details as well as its own area, and asks a technician when either area does. Changed bank details are where payment fraud starts.
  • Only documented operations. Neo sends only the writes in Xero’s published API definitions, each with its own method, and refuses any other.
  • Files stay in Xero. Neo does not download PDFs or attachments, and does not upload files.
  • Neo keeps its own connection. Neo never disconnects the custom connection.
  • Path safety. Neo rejects suspicious URL paths (anything that contains .., for example) before they reach Xero.

​
If Xero refuses Neo’s requests

​
Disconnecting Xero

1

Open the integration

In the Neo Dashboard, open Integrations and select the Xero card.
2

Disconnect

Click Disconnect and confirm. Neo removes the keys from Key Vault. To end the connection at Xero as well, delete the custom connection in My Apps or disconnect it in Xero under Connected apps.
Neo keeps your Organization Mapping, including any mapping you set by hand, so a later reconnect continues from the same state. Agents that use Xero stop working until you connect it again.

​
Security

  • The Client Secret is stored in Azure Key Vault, never in plaintext.
  • All traffic to Xero goes over HTTPS, to api.xero.com and identity.xero.com only.
  • Write access is opt-in per agent.