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.

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.)

Connecting a Xero organisation to a model

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

1

Open the model

Open the model you want to link.

2

Go to the integration panel

Go to Importing and Data Inputs or the Xero Integration panel.

3

Initiate connection

Click Connect Xero (or equivalent). You will be redirected to the Xero sign in page.

4

Sign in

Sign in with your Xero credentials if you are not already signed in.

5

Select organisation

Choose the organisation (tenant) you want to connect.

6

Approve permissions

Review and approve the requested permissions.

7

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.

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:

1

Open integration panel

Open the Xero integration panel for the affected model.

2

Reconnect

Click Reconnect Xero (or similar).

3

Repeat OAuth sign-in

Repeat the OAuth sign in and organisation selection.

4

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.

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

• Build a Consolidated Forecast Model

• Authentication (OAuth)

• Allowed Operators