> For the complete documentation index, see [llms.txt](https://help.modelreef.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.modelreef.io/help/quickbooks-integration/authentication-oauth.md).

# Authentication (OAuth)

This article explains how to connect your QuickBooks Online (QBO) company to a Model Reef model using OAuth, what the connection is used for, and how to fix common authentication issues.

You will learn how to:

* Connect a QBO company to a specific model.
* Understand what data Model Reef reads from QBO.
* Work with multiple companies or environments.
* Reconnect if access is revoked or tokens expire.

***

## What the QuickBooks connection is used for

The QuickBooks integration is used to:

* Import the Chart of Accounts (COA).
* Import historical actuals for P\&L and Balance Sheet accounts.
* Refresh actuals over time so your model stays aligned with the ledger.

By default, Model Reef uses **read only** access for these flows. It does not post journals, invoices or other operational transactions into QuickBooks through this integration.

Any budget push or other write behaviour is handled through explicit, separate workflows.

***

## Connecting a QuickBooks company to a model

You connect QuickBooks at the **model** level. Each Model Reef model can be linked to one QuickBooks company.

{% stepper %}
{% step %}

### Open the model

Open the model you want to link.
{% endstep %}

{% step %}

### Go to the integration panel

Go to the **Importing and Data Inputs** area or the **QuickBooks Integration** panel.
{% endstep %}

{% step %}

### Start the connection

Click **Connect QuickBooks**.
{% endstep %}

{% step %}

### Sign in to Intuit

You will be redirected to the Intuit sign in page. Sign in with your QuickBooks Online credentials if you are not already signed in.
{% endstep %}

{% step %}

### Select company and permissions

Select the **company** you want to connect. Review and accept the requested permissions.
{% endstep %}

{% step %}

### Return to Model Reef

You will be returned to Model Reef and should see a confirmation that the company is now linked. Once connected, you can import the COA and historical actuals into this model.
{% endstep %}
{% endstepper %}

***

## Permissions and security

The QuickBooks OAuth flow grants Model Reef a scoped access token that allows it to:

* Read the Chart of Accounts.
* Read account balances and transaction level data needed to build actuals.
* Read basic company metadata that may be useful for reporting.

The integration does **not** use this connection to:

* Create or edit invoices or bills.
* Post or update general ledger journals.
* Change users, tax settings or other administrative options in QuickBooks.
* Run payroll or bank feed operations.

Tokens are stored securely and refreshed using Intuit's standard OAuth refresh mechanism where supported.

If you revoke access from within QuickBooks, the connection inside Model Reef will stop working until you reconnect.

***

## Connecting multiple companies

You can connect different Model Reef models to different QuickBooks companies. Common patterns include:

* One model per legal entity, each linked to the corresponding QBO company.
* One consolidation model that pulls COA and actuals from several companies, mapping each into branches.
* Test or sandbox models linked to QBO sample companies for training and experimentation.

Each model stores its own QuickBooks connection. Connections are not shared across models.

***

## Reconnecting and troubleshooting authentication

If authentication fails or expires, you may see:

* Errors when starting a COA or actuals import.
* Messages indicating that the QuickBooks token has expired or that access was revoked.
* Partial or empty results when attempting to refresh data.

To fix:

{% stepper %}
{% step %}

### Open the integration panel

Open the **QuickBooks Integration** panel for the affected model.
{% endstep %}

{% step %}

### Reconnect

Click **Reconnect QuickBooks**.
{% endstep %}

{% step %}

### Complete OAuth

Complete the OAuth sign in and company selection again.
{% endstep %}

{% step %}

### Rerun imports

Once reconnected, rerun any COA or actuals imports that failed. If you have access to several QuickBooks companies, confirm you are selecting the intended one for this model.
{% endstep %}
{% endstepper %}

***

## Best practices

* Use a QuickBooks user account that has read access to all relevant accounts and periods.
* Avoid linking production models to demo or training companies.
* Maintain a simple mapping between Model Reef models and QuickBooks companies and document this for your team.
* If you perform security reviews that revoke third party access, remember to reconnect affected models afterwards.

***

## Related articles

* [Education Providers (Private, Vocational)](/use-cases/education-providers-private-vocational.md)
* [Build a Driver Based Forecast](/how-tos/core-modelling/build-a-driver-based-forecast.md)
* [Authentication (OAuth)](/help/quickbooks-integration/authentication-oauth.md)
* [Branch Selector](/syntax/understanding-the-interface/branch-selector.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.modelreef.io/help/quickbooks-integration/authentication-oauth.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.