> 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/xero-integration/authentication-oauth.md).

# Authentication (OAuth)

This article explains how to connect your Xero organisation to a Model Reef model using OAuth, what permissions are required, and how the connection is used for COA and actuals import.

You will learn how to:

* Connect a Xero tenant to a model.
* Understand what data Model Reef reads.
* Handle multiple organisations and environments.
* Reconnect if access is revoked or tokens expire.

## What the Xero connection is used for

The Xero 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.

{% hint style="info" %}
Model Reef uses **read only** access. It does not post journals, invoices or other transactions back into Xero from this integration.

(If you later use budget push or other write operations, they are handled by separate, explicit workflows.)
{% endhint %}

## Connecting a Xero organisation to a model

You connect Xero at the model level. Each model can be linked to one Xero organisation.

{% stepper %}
{% step %}

### Open the model

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

{% step %}

### Go to the integration panel

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

{% step %}

### Initiate connection

Click **Connect Xero** (or equivalent). You will be redirected to the Xero sign in page.
{% endstep %}

{% step %}

### Sign in

Sign in with your Xero credentials if you are not already signed in.
{% endstep %}

{% step %}

### Select organisation

Choose the **organisation** (tenant) you want to connect.
{% endstep %}

{% step %}

### Approve permissions

Review and approve the requested permissions.
{% endstep %}

{% step %}

### Return to Model Reef

You will be redirected back to Model Reef and see a confirmation that the connection is active.

Once connected, you can begin a COA import and actuals import for that model.
{% endstep %}
{% endstepper %}

## Permissions and security

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

* Read the Chart of Accounts.
* Read transactions and balances needed to compute account actuals.
* Read basic organisation metadata relevant to reporting.

The platform does **not** use the integration to:

* Create or edit invoices.
* Post or update journals.
* Modify contacts, users or settings in Xero.
* Run payroll or bank feeds.

Access tokens are stored securely and refreshed via the standard OAuth refresh token flow where supported.

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

## Connecting multiple organisations

You can connect different Model Reef models to different Xero organisations. Common patterns:

* One model per legal entity, each connected to its own Xero tenant.
* One consolidated model with COA imports from several entities, each mapped into branches.
* Sandbox or test models linked to a demo Xero organisation.

Each model stores its own Xero connection metadata. There is no automatic sharing of connections between models.

## Reconnecting and troubleshooting authentication

If authentication fails or expires, you may see:

* Errors when attempting to refresh COA or actuals.
* Messages indicating that the Xero token has expired or been revoked.
* Missing or partial data on new sync attempts.

To fix the issue, follow these steps:

{% stepper %}
{% step %}

### Open integration panel

Open the Xero integration panel for the affected model.
{% endstep %}

{% step %}

### Reconnect

Click **Reconnect Xero** (or similar).
{% endstep %}

{% step %}

### Repeat OAuth sign-in

Repeat the OAuth sign in and organisation selection.
{% endstep %}

{% step %}

### Refresh imports

Once reconnected, rerun the COA and actuals imports or refresh as needed.

If you have access to several Xero organisations, double check that you have selected the correct one for this model.
{% endstep %}
{% endstepper %}

## Best practices

* Use a Xero user with sufficient read permissions to all relevant accounts.
* Avoid connecting production models to temporary or demo organisations.
* Document which Model Reef model corresponds to which Xero tenant, especially in multi entity setups.
* Re-authenticate promptly if Xero access is revoked during security reviews.

## Related articles

* [Contract Renewal Forecasting](/use-cases/telecommunications-and-it-services/contract-renewal-forecasting.md)
* [Build a Consolidated Forecast Model](/how-tos/core-modelling/build-a-consolidated-forecast-model.md)
* [Authentication (OAuth)](/help/xero-integration/authentication-oauth.md)
* [Allowed Operators](/syntax/formula-syntax/allowed-operators.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/xero-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.