> ## 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 QuickBooks Online to Neo

> Create an Intuit app, authorize your QuickBooks company, save the keys in Neo, and decide what each agent can do

You connect QuickBooks Online once at the MSP level, then turn it on per agent. You need four values: your Intuit app's **Client ID** and **Client Secret**, a **Refresh Token**, and your company's **Realm ID**. You create the app in your own Intuit Developer account, so the keys and the connection belong to you.

## 1. Create an app in the Intuit Developer portal

<Steps>
  <Step title="Sign in to the Intuit Developer portal">
    Go to [developer.intuit.com](https://developer.intuit.com) and sign in, or create a free account. Use an account of a QuickBooks admin: only an admin can authorize the company in step 2.
  </Step>

  <Step title="Create the app">
    Open **My Hub > App dashboard** and create an app with the **com.intuit.quickbooks.accounting** scope. Name it so your team recognizes it, for example "Neo Agent".
  </Step>

  <Step title="Get production keys">
    Open the app, then **Keys and credentials > Production**. Intuit asks for your app details (a host domain, launch and disconnect URLs, an end user licence agreement and a privacy policy URL) and an app assessment questionnaire before it shows production keys. A private app used only by your own company is enough; you do not publish it on the Intuit App Store. Once Intuit approves the questionnaire, copy the **Client ID** and the **Client Secret**.
  </Step>

  <Step title="Allow the OAuth 2.0 Playground">
    In the app's **Settings > Redirect URIs**, on the **Production** tab, add `https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl` and save.
  </Step>
</Steps>

## 2. Authorize your company and copy the refresh token

<Steps>
  <Step title="Open the OAuth 2.0 Playground">
    Open the [OAuth 2.0 Playground](https://developer.intuit.com/app/developer/playground). Under **Select app**, choose your app with its production keys, and select the **com.intuit.quickbooks.accounting** scope.
  </Step>

  <Step title="Connect your company">
    Select **Get authorization code**, sign in as a QuickBooks admin, choose your company and select **Connect**. The Playground shows the **Authorization code** and the **Realm ID**. Copy the Realm ID.
  </Step>

  <Step title="Get the tokens">
    Select **Get tokens** and copy the **Refresh token**.
  </Step>
</Steps>

<Warning>
  **Enter the refresh token in Neo only.** Intuit replaces a refresh token from time to time, and the old one stops working when a new one is issued. Neo stores each new token in place of the old one. If another tool or script uses the same token, one of the two stops working, and you must get a new token in the Playground.
</Warning>

## 3. Save the keys in Neo

<Steps>
  <Step title="Open Integrations">
    In the Neo Dashboard, open [**Integrations** → **QuickBooks Online**](https://dashboard.neoagent.io/integrations?open=quickbooks_online), under Accounting.
  </Step>

  <Step title="Enter the values">
    Paste the **Client ID**, **Client Secret**, **Refresh Token** and **Realm ID**. Click **Save**.

    Neo uses the refresh token with Intuit before it saves, then reads your company with the new access token. Wrong app keys or a token that no longer works are refused on the spot. When the new token cannot read the company (a Realm ID of another company, or a user who is no longer a QuickBooks admin), the save fails. Neo keeps the token Intuit returned, so reload the page, correct the Realm ID or authorize as an admin, and save again.
  </Step>
</Steps>

### Keep the connection alive

A refresh token expires after 100 days without use. Neo maps your QuickBooks customers to PSA companies after each PSA sync, and that run renews the token, so an account whose PSA keeps syncing stays connected. Intuit also ends every authorization after five years; then you authorize again.

If Intuit refuses the token, for example after someone disconnected the app in QuickBooks or used the same token elsewhere, Neo shows an action item in your inbox and emails your admin. Get a new refresh token in the Playground, as in step 2, and save it in Neo.

## 4. Turn QuickBooks Online on per agent

Each agent decides whether it uses QuickBooks Online and which areas it can touch. Open the agent, go to the Integrations section, and configure the QuickBooks Online block.

### Pick an access profile

<CardGroup cols={2}>
  <Card title="Read Only" icon="magnifying-glass">
    Every area read only, emails off. The agent searches invoices, customers, payments and reports, and never changes anything.
  </Card>

  <Card title="Helpdesk" icon="headset">
    Customers and Employees & Time read and write, each change with technician approval. Everything else read only, emails off.
  </Card>

  <Card title="IT Admin" icon="user-gear">
    Every writable area read and write. The agent creates and updates customers, invoices, payments, bills, products and time on its own. Emails to customers and vendors, journal and account changes, and company settings wait on a technician.
  </Card>

  <Card title="Full Automation" icon="bolt">
    Every supported write runs with no approval, emails to customers and vendors included.
  </Card>
</CardGroup>

### Or set each area by hand

| Area | Access levels you can pick | Notes |
| - | - | - |
| **Customers** | Disabled, Read Only, Read and Write | Customers and sub-customers. A customer is made inactive, never deleted. |
| **Sales & Invoices** | Disabled, Read Only, Read and Write | Invoices, estimates, credit memos, sales and refund receipts, payments. Read Only is enough to search invoices. Deleting and voiding follow your approval setting. |
| **Emails to Customers & Vendors** | Disabled, Read and Write | Emailing an invoice, estimate, credit memo, receipt or payment receipt to the customer, or a purchase order to the vendor, from your QuickBooks. Creating an invoice never emails it. Consider approval here. |
| **Vendors & Purchases** | Disabled, Read Only, Read and Write | Vendors, bills, bill payments, purchase orders, expenses and vendor credits. |
| **Accounts, Journals & Banking** | Disabled, Read Only, Read and Write | The chart of accounts, journal entries, deposits, transfers, budgets and recurring templates. These change the books as a whole, so consider approval here. |
| **Products, Tax & Lists** | Disabled, Read Only, Read and Write | Products and services, classes, locations, terms, payment methods, tax codes and rates, currencies. |
| **Employees & Time** | Disabled, Read Only, Read and Write | Employees and time activities. |
| **Attachments & Notes** | Disabled, Read Only, Read and Write | Notes, and the names of files attached to records. |
| **Company Settings** | Disabled, Read Only, Read and Write | Company details and preferences. A change applies to every record, so consider approval here. |
| **Reports** | Disabled, Read Only | Profit and loss, balance sheet, aged receivables and payables, customer and vendor balances, sales and transaction lists. |

## 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 Customers & Vendors.
* **A search reads one area.** Neo reads which record type a search asks for and checks the area for it, so an agent with Sales & Invoices cannot search your employees.
* **A delete or void names its record.** Neo refuses one without the record's id and sync token, so when the area asks for approval, the technician approves the exact record.
* **Only documented operations.** Neo sends only the operations in Intuit's Accounting API reference, each with its own method, and refuses any other call.
* **Files stay in QuickBooks.** Neo does not download PDFs or attachments, and does not upload files.
* **Path safety.** Neo rejects suspicious URL paths (anything that contains `..`, for example) before they reach QuickBooks.

## If QuickBooks refuses Neo's requests

| What comes back | Cause | Fix |
| - | - | - |
| An inbox action item to reconnect | The refresh token expired, was used elsewhere, or the app was disconnected in QuickBooks | Get a new refresh token in the Playground and save it in Neo. |
| `401` | The connection lost access, for example the admin who authorized it is no longer an admin | Authorize again as a QuickBooks admin. |
| `403` | Your QuickBooks subscription or the user does not allow the operation | Check the QuickBooks plan and the user's rights. |
| `429` | Too many requests: QuickBooks allows 500 a minute per company | Wait, then try again. |

## Disconnecting QuickBooks Online

<Steps>
  <Step title="Open the integration">
    In the Neo Dashboard, open **Integrations** and select the QuickBooks Online card.
  </Step>

  <Step title="Disconnect">
    Click **Disconnect** and confirm. Neo removes the keys from Key Vault and stops using its cached access token. To end the authorization at Intuit as well, disconnect the app in QuickBooks under **Apps**.
  </Step>
</Steps>

Neo keeps your Organization Mapping, including any mapping you set by hand, so a later reconnect continues from the same state. Agents that use QuickBooks Online stop working until you connect it again.

## Security

* The Client Secret and the refresh token are stored in Azure Key Vault, never in plaintext.
* All traffic to Intuit goes over HTTPS, to `quickbooks.api.intuit.com` and `oauth.platform.intuit.com` only.
* Write access is opt-in per agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.