By KYN AI Advisory Team — AI implementation specialists, Singapore
An AI agent can connect to Xero through its Accounting API using OAuth 2.0. It can read contacts, invoices, bills, payments, bank transactions and reports, and it can create and update most of them, including manual journals. It works within granular scopes you grant and within rate limits per organisation. Treat the API as a way to draft and read, and keep posting, payment and filing decisions with a named person.
How does an agent authenticate to Xero?
Xero uses OAuth 2.0. Your organisation authorises an app, and the app receives a short-lived access token and a refresh token. The agent never sees a password.
Xero documents several flows in its OAuth 2.0 guides:
- Authorisation code flow. A person signs in to Xero and consents to the app. Use this for a system that acts for your own organisation or for several client organisations.
- Custom Connections. Built for a single organisation, without the interactive consent step. Check Xero's Custom Connections documentation for the current terms, regions and costs before you plan around it.
Practical points for an agent:
- Store the refresh token in a secrets manager in your cloud account, not in code or a spreadsheet.
- Refresh tokens rotate and expire if unused. Build a check that alerts when a refresh fails, because a silent expiry means the agent stops with no error in the ledger.
- One connection per Xero organisation (a tenant). A group with five entities has five tenants and five sets of limits.
What scopes should you grant?
Scopes limit what the token can do. Xero has moved from broad scopes to granular ones. Its granular scopes FAQ says apps created after 2 March 2026 get the granular scopes automatically, and the broad accounting.transactions scope is split into separate scopes for invoices, payments, bank transactions and manual journals. Existing apps have a transition period, so check the scopes page and the changelog for the current dates.
The principle for an agent is least privilege. Grant only what each job needs.
| Agent job | Scopes it needs (granular names) | |---|---| | Read bills and match to a ledger | invoices read, contacts read | | Draft bills from emails | invoices write, contacts read | | Reconcile payments | payments read, bank transactions read | | Prepare a revaluation or payroll journal | manual journals write | | Month-end reporting | reports read |
Use separate apps, and so separate tokens, for separate jobs where you can. A read-only reporting app should not hold a write scope. If the draft-bills agent is compromised or misled, the damage is limited to drafts.
What can the API do for finance work?
- Contacts. Read and create suppliers and customers, including bank details on contacts where Xero exposes them.
- Invoices and bills. Create, update and read sales invoices and purchase bills, with line items, tax types, tracking categories and attachments. Status can be draft, submitted, authorised or paid. An agent should create bills as draft or awaiting approval, never straight to authorised.
- Payments. Create payments against invoices and bills, read payments, and create batch payments.
- Bank transactions and statements. Read bank transactions; spend and receive money transactions can be created. Bank statement lines come in through bank feeds or statement import.
- Manual journals. Create and read, including with a posting date. Use for revaluation, accruals and payroll journals.
- Reports. Pull Profit and Loss, Balance Sheet, Trial Balance and aging reports as data.
- Attachments. Attach the source PDF to the bill so the record carries its evidence.
- Webhooks. Subscribe to contact and invoice change events, so the agent reacts to a change and does not poll.
What does the API not do?
Check each of these against the current API reference before you promise a workflow, because Xero adds endpoints over time. As of our last check these are the common gaps in practice:
- Bank reconciliation as a click. The API lets you read bank transactions and create payments or spend money entries, but it does not give you the interactive match-and-reconcile screen. For how automated matching works around this, see Xero bank feeds vs automated bank reconciliation.
- Filing returns. Singapore GST returns are filed with IRAS, not through Xero's API. The agent can prepare the figures. A person files.
- Everything in the user interface. Some settings and reports have no endpoint. Treat the UI as the exception route and log when a person has to use it.
- Unlimited volume. See rate limits below.
- Closed periods. If a lock date is set, the API will reject entries dated before it. That is a feature. Keep the lock date set.
What are the rate limits, and how do you design around them?
Xero's rate limit documentation sets limits per organisation connection and per app. At the time of checking, these include 5 concurrent calls per tenant, 60 calls per minute per tenant and 10,000 calls per minute across all tenants for an app, plus a daily cap that depends on your plan tier. Exceeding a limit returns HTTP 429 with a Retry-After header.
Design rules:
- Honour Retry-After. Wait the stated time, then retry. Do not hammer.
- Batch. Create invoices in one call with many items where the endpoint allows it.
- Use webhooks and
If-Modified-Since. Fetch only what changed since the last run. - Queue writes. One worker per tenant. Five concurrent calls is a low ceiling.
- Make writes idempotent. If a call times out, you may not know whether it landed. Store your own reference on each created bill and check for it before retrying, so a retry does not create a duplicate.
What should wait for a person?
The API will let an agent do things the business should not allow without a decision. Hold these:
- authorising a bill or invoice;
- creating a payment or a batch payment;
- posting a manual journal that moves profit;
- changing bank details on a contact;
- voiding or deleting anything.
The agent drafts, attaches evidence and posts a note. A named person approves in Xero or in the agent's own review screen, and the approval is logged with the actor. See how to set approval gates for high-risk agent actions.
Where KYN fits
KYN connects agents to the accounting system you already run. Tokens sit in a secrets manager in your cloud account, each agent has its own restricted account and scopes, and every action is logged with the actor. Money, filings and deletions wait for a named person. For a finance software startup we took receipts, claims and GST to production in six weeks. See integrations and finance systems.
The first 14 days are a review of your stack and interviews with your team. A full build ships in under 90 days.
Frequently asked questions
Can an agent reconcile my bank account in Xero?
It can read bank transactions and statement data, propose matches and create the payment or spend entries a match needs. It cannot press Reconcile for you through the API. A person confirms in Xero, or the system records the match on its own side.
Is it safe to give an agent write access?
Only with narrow scopes, draft status, a lock date and a log. The agent creates drafts and a person authorises them. Do not grant payment or journal scopes to an agent that reads email.
Does the agent work with multiple Xero organisations?
Yes. Each organisation is a separate tenant with its own consent and its own rate limits. Keep one token set per tenant and one queue per tenant.
Checked 30 October 2026.
Curious whether Marketing agents fits your business? Talk to KYN on WhatsApp — no forms, just a conversation.
