Skip to main content

Xero

Read and create Xero invoices, contacts, payments and reports for one organisation.

Connect it with: Sign in (OAuth), API key. Xero's own documentation: https://developer.xero.com/documentation/guides/oauth2/auth-flow/.

What agents can do​

Connect Xero so the agents working your tasks can reach it. With it connected, they can:

  • Find invoices, bills and credit notes and report what is overdue or unpaid.
  • Create draft invoices or bills from a task's line items for a person to approve.
  • Look up or add contacts and check their balances.
  • Pull the profit and loss, balance sheet or aged receivables report for a period.

Before you start​

  • A Xero organisation, and a Xero user who may connect apps to it (Connect), or a paid Xero Custom Connection for it.
  • For a Custom Connection: an account at https://developer.xero.com to create it, and a user with the Adviser role in the organisation to authorise it.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Xero​

This is the quickest way in: you sign in to Xero and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for Xero and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Select Connect Xero. Xero's sign-in window opens.
  5. Sign in to Xero if asked, check the access listed, and approve it.
  6. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at Xero yet. Use an API key, or your own OAuth app, until it does.

Scopes Jaah requests​

Jaah asks Xero for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

ScopeWhy Jaah asks for itRequired
offline_accessStay connected: lets Jaah renew access without asking you to sign in againYes
accounting.invoicesRead and create invoices, bills and credit notesYes
accounting.contactsRead and add contacts and their balancesYes
accounting.paymentsRead and record paymentsYes

Connect with an API key​

Prefer this when you cannot sign in with Xero — for example a service account, or a token your admin issued. On the Connect screen select Use an API key instead.

Find each value first:

  • Client ID: At https://developer.xero.com/app/manage select New app, choose Custom connection as the integration type, name it Jaah, tick the scopes agents need, and pick the user who authorises it. Once that user approves it in Xero and the connection is paid for, open the app's Configuration page and copy the Client id.
  • Client secret: On the same Configuration page select Generate a secret and copy it straight away: Xero shows it only once.
  • Tenant ID: Connect fills it. For a Custom Connection: the ID of the Xero organisation the connection was authorised for. A developer can read it as tenantId from GET https://api.xero.com/connections with the connection's token; Xero support can also give it to you.
  • Scope (optional): Leave blank to get every scope the custom connection was granted. Otherwise list a subset separated by spaces, such as accounting.invoices.read accounting.contacts.read.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Xero card.
  2. Name the secret and choose who can use it.
  3. Select Use an API key instead.
  4. Fill in Client ID, Client secret, Tenant ID, Scope.
  5. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Connect Xero always runs on this Jaah's own client, so there is no app of your own to create.

Test the connection​

Select Test on the secret. Jaah calls Xero's API once (GET https://api.xero.com/connections) with the stored values, and shows who it answered as, or which value Xero refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

A key connection hands the agent its fields: client_id, client_secret, tenant_id, scope.

Tell the agent in your task description which secret to use, for example “use the Xero secret org/xero”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Xero once the test passes. Steps: Replace or delete a secret.
  • Reconnect: when Xero ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Xero's side too, revoke Jaah in Xero's settings, or revoke or delete the key at Xero.

Limitations​

  • One secret reaches one Xero organisation: Connect keeps the organisation you pick at consent, and a Custom Connection is tied to the one it was authorised for. Connect again for another organisation.
  • Connect asks for invoices, contacts and payments; reports need a Custom Connection granted the report scopes.
  • Xero limits each organisation to 60 calls a minute and 5,000 a day; agents that reach the limit wait for it to reset.
  • Connections created since March 2026 use Xero's granular scopes, such as accounting.invoices.read, instead of the older broad ones.
  • Agents can do only what the connected Xero account and its granted scopes allow.

Troubleshooting​

Test says Xero rejected the client credentials or the requested scope

The client ID or secret is wrong, the secret was regenerated, or Scope names a scope the connection was not granted. Copy both values again from the app's Configuration page, clear Scope, and select Replace.

Test says Xero accepted the credentials but no organisation matches this Tenant ID

Tenant ID belongs to another organisation. Read tenantId again from GET https://api.xero.com/connections and correct it.

Test fails although the values are right

The Custom Connection is not paid for or not yet authorised. Check its status at https://developer.xero.com/app/manage.

Connect ends with no organisation or site for this sign-in

No organisation was ticked on Xero's consent page. Select Connect again and tick the organisation agents should reach.

Still stuck? Select Test and read the result: it names the value Xero refused and the status it answered.

FAQ​

Should I connect or use a Custom Connection?

Connect is free and acts as you. A Custom Connection is paid per organisation but needs no person to stay signed in.

Does Test change anything in Xero?

No. It reads the connected organisation with the secret's token.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Xero account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.