> For the complete documentation index, see [llms.txt](https://docs.zwapgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/xero.md).

# Xero

Complete Xero onboarding from your client backend.

**Preview** · [What this means for your integration](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#preview)

Your backend completes Xero authorization, selects an organization and sends its tokens and tenant ID. **Zwapgrid checks access and takes over token refresh.**

First, complete the [shared prerequisites and example setup](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#before-you-start).

## What you need

* Your own Xero OAuth web application. See the [Xero setup guide](https://docs.zwapgrid.com/client-portal/systems/setup-guides/xero.md).
* A Published Xero System Setting containing that application's client ID and secret, belonging to your Zwapgrid client.
* The same client ID and secret available securely to your backend for code exchange.
* Your backend callback URL registered on the Xero application. Use this URL for headless authorization; keep the guided callback if you also use guided onboarding.

## OAuth scopes

Zwapgrid needs these scopes to access your customer's accounting data:

```
openid profile email accounting.contacts accounting.settings accounting.attachments accounting.invoices accounting.reports.profitandloss.read offline_access
```

## 1. Prepare the connection

1. Use the [Consent created in the shared workflow](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#1-create-a-consent). Make sure `systemsSettings.xero` contains your published setting ID.
2. Start Xero's authorization-code flow at `https://login.xero.com/identity/connect/authorize` with `response_type=code`, your application's `client_id`, registered backend callback, the [OAuth scopes above](#oauth-scopes), and random, expiring session/Consent-bound `state`.
3. Validate callback state and exchange the code in your backend at `https://identity.xero.com/connect/token`. Send a form-encoded POST with `grant_type=authorization_code`, the code and exact `redirect_uri`, authenticating with HTTP Basic using your application's client ID and secret.
4. Call `GET https://api.xero.com/connections` with the resulting bearer access token. Choose an accessible entry with `tenantType: ORGANISATION`. You can select the sole organization automatically, or ask the customer to choose when several are available. Use its `tenantId`, not the Xero connection `id`.
5. If your backend is refreshing these tokens, stop it and wait for any refresh in progress to finish. Send the latest tokens and selected tenant ID once. Keep your refresh process stopped until you confirm the result.

See [Xero's authorization-code flow](https://developer.xero.com/documentation/guides/oauth2/auth-flow/) for provider authorization and token requests.

## 2. Send the request

```json
{
  "source": "xero",
  "credentials": {
    "accessToken": "<latest-access-token>",
    "refreshToken": "<latest-refresh-token>",
    "tenantId": "<selected-organization-UUID>"
  }
}
```

All three fields are required. Access tokens are limited to 8192 characters and refresh tokens to 4096 characters. `tenantId` must be a non-empty UUID. Do not send the authorization code, redirect URI, PKCE verifier or application secret.

Send both tokens for the selected organization. Zwapgrid verifies access before completing the connection. Your customer does not need to authorize again or choose an organization in Zwapgrid.

Replace the placeholders and save this body as a protected `connection.json` on your backend. Set the [example variables](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#set-up-the-examples), including a new UUID in `CORRELATION_ID`, then send the request once:

```sh
curl --request POST \
  "$CONSENTS_API_BASE_URL/api/v1/consents/$CONSENT_ID/connection" \
  --header "x-api-key: $ZWAPGRID_API_KEY" \
  --header "x-correlation-id: $CORRELATION_ID" \
  --header 'Content-Type: application/json' \
  --data-binary @connection.json
```

## 3. Check the result

Expect HTTP 201 with `source: xero` and `state: completed`. [Optionally verify the connection](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#optional-verify-the-connection).

After confirmed success, Zwapgrid owns refresh. Let Zwapgrid manage refresh for this authorization. Do not keep refreshing it in your backend or submit its tokens for another connection. If POST is uncertain, keep refresh paused and recover with GET. A missing result does not prove the submitted refresh token is usable. Authorize again if you cannot confirm whether the tokens are still valid; do not resubmit old tokens.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/xero.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
