> ## Documentation Index > Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt > Use this file to discover all available pages before exploring further. # Connecting Xero to Neo > Create a Xero custom connection, authorise your organisation, save the keys in Neo, and decide what each agent can do 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. > [!NOTE] > > 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](https://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**](https://dashboard.neoagent.io/integrations?open=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 | Area | Access levels you can pick | Notes | | - | - | - | | **Invoices, Bills & Quotes** | Disabled, Read Only, Read and Write | Sales invoices and bills, credit notes, quotes, purchase orders, repeating invoices, linked transactions, expense claims and receipts, with their history and notes. Read Only is enough to report on invoices. | | **Emails to Contacts** | Disabled, Read and Write | Emailing an invoice to its contact from your Xero organisation. Creating an invoice never emails it. Consider approval here. | | **Payments** | Disabled, Read Only, Read and Write | Payments, batch payments, overpayments, prepayments and their allocations. | | **Contacts** | Disabled, Read Only, Read and Write | Customers and suppliers, with their details, tax number and bank account details, and contact groups. | | **Bank Account Details** | Disabled, Read Only, Read and Write | Needed beside the record's own area for any write that sets a bank account (a contact's, an account's, an employee's or a super fund's), and for an employee's payment methods. Consider approval here. | | **Bank Transactions & Statements** | Disabled, Read Only, Read and Write | Spend and receive money, bank transfers, bank statement lines and reconciliation, account balances and movements, bank feeds. | | **Accounts & Journals** | Disabled, Read Only, Read and Write | The chart of accounts, manual journals, the general ledger and conversion balances. These change the books as a whole, so consider approval here. | | **Reports & Budgets** | Disabled, Read Only | Aged receivables and payables, profit and loss, balance sheet, trial balance, bank, budget and executive summaries, tax and 1099 reports, budgets and financial statements. | | **Items & Organisation Settings** | Disabled, Read Only, Read and Write | Items, organisation details, users, currencies, tax rates, tracking categories, branding themes and invoice reminder settings. A change applies to every record, so consider approval here. | | **Attachments & Files** | Disabled, Read Only, Read and Write | The list of files attached to records, and the Files library. | | **Fixed Assets** | Disabled, Read Only, Read and Write | Fixed assets and asset types. | | **Projects & Time** | Disabled, Read Only, Read and Write | Projects, tasks and time. | | **Payroll Employees & Leave** | Disabled, Read Only, Read and Write | Employees with their personal, employment, tax and pay details, and leave. | | **Pay Runs, Payslips & Timesheets** | Disabled, Read Only, Read and Write | Pay runs, payslips and timesheets. A posted pay run pays people, so consider approval here. | | **Payroll Settings** | Disabled, Read Only, Read and Write | Payroll calendars, pay items, earnings rates, deductions, leave types, super funds and the like. | ## 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 | What comes back | Cause | Fix | | - | - | - | | `401`, or a token error | The connection was removed or is no longer authorised, its secret changed, or a scope saved in Neo is no longer ticked on it | Check the connection in **My Apps**, then save the Client ID, a current secret and its scopes in Neo again. | | `403` | The connection's scopes do not include that call | Tick the scope on the connection and add it to **Scopes** in Neo. | | `429` | Too many requests: Xero allows 60 a minute, 5 at a time, and a daily limit per organisation | Wait, then try again. | ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.