ChatGPT + Xero + your chosen agent
Connect Xero to
Codex or Hermes
a working Xero Accounting API connection in your chosen Codex project or Hermes Agent, with reusable skills that can read accounting data and prepare approved changes. You will prove the connection in a demo company, test the skills where they actually run, and decide what is ready for real work.
Keep one ChatGPT conversation open to guide the whole exercise. Let the AI inspect your environment, research current documentation, explain options and do the approved technical work. You supply the business context, make decisions and review the evidence.
Use one short prompt at a time. The numbered stages are a route through the lesson; you can return to any stage when a question or test exposes a gap. The technical reference is for ChatGPT and your instructor to check, not a list of commands to memorise.
Review status: teaching draft, prepared 8 October 2026. This guide describes tests for students to perform. No Xero account has been connected and no live-account test has been performed in preparing it.
Three modes. Keep the conversation moving.
This walkthrough follows Darryl Wong's DUO Framework version 0.2 (opens in a new tab).
- Discover: let the AI expand the context, check current sources and surface unknowns
- Understand: add your situation, challenge assumptions and decide what fits
- Output: ask for the next useful result from those decisions, then review it
These are conversation modes, not three magic words or a fixed prompt formula. You decide when to move into Output and when the work is complete. A plan or proposed change is not approval to execute it.
For example, if the connection works but the company is wrong, return to Discover to find out why. If an invoice looks plausible but you cannot defend its tax treatment, stay in Understand and involve your accountant. A polished answer does not close an unresolved question.
Before you start
Keep control of access and changes
Have your ChatGPT app, an authorised Xero account, a password manager and either a working Codex project or the Hermes setup from the previous class guide (opens in a new tab). Use Xero's Demo Company or another explicitly approved test organisation with fictional data.
One conversation, two possible destinations: ChatGPT coordinates the work. The integration runs in your selected Codex environment or on your Hermes VPS. A normal chat or uploaded file does not automatically give an app a working runtime, browser control or a Xero connection. Ask ChatGPT to check the actual tools available before choosing the route.
Browser automation disclaimer: try the browser-assisted route in this ChatGPT app first. Xero's developer terms, section 29 (opens in a new tab) require Xero's explicit authorisation for automated interactions that simulate user actions. Check that authorisation before ChatGPT operates the portal; this guide and your own permission do not replace it. Where authorisation or browser access is unavailable, use the manual steps below. You handle sign-in, credentials, new agreements and consent yourself in either route.
Keep passwords, client secrets, access tokens, refresh tokens and recovery codes out of chat, screenshots, source files and Git. Enter and submit credentials yourself in the approved private credential store or secure sign-in flow. Never paste a callback URL containing an authorisation code into chat.
Full relevant accounting API access needs an explicit scope review. It does not approve every action that access makes possible. Start with writes locked. No real payments, money transfers, tax filing, invoice sending or changes to live records are generic connection tests.
Begin with stage 1The walkthrough
Study checkpoints do not certify production readiness
Stage 1 of 11
Start with the accounting work
Attach this guide to your ChatGPT conversation, then say:
Help me connect Xero to my Codex project or Hermes Agent. Use this guide, keep the prompts simple and take me one step at a time.
Discover
Explore what we need for a useful accounting connection. Check current official documentation and tell me what is uncertain.
Understand
I work with [organisation and country]. I want help with [accounting tasks]. What decisions do I need to make?
Give only the context needed now. Choose one first task, such as reviewing overdue invoices, explaining a profit and loss report, or preparing a draft invoice from an approved brief. Identify the accounting period, currency, who owns the books and who can approve changes.
Output
Draft our setup plan and success checks for this task.
Your checkpoint
you can explain the task, who it serves, what a correct result looks like and which data or actions are outside the exercise. The plan names unresolved questions rather than hiding them.
Stage 2 of 11
Choose where the connection will run
Discover
Inspect my available setup. Compare connecting Xero to my Codex project and to Hermes, including how each would sign in.
ChatGPT should inspect the real target before recommending commands, packages or a connection method. It should say which browser and computer it can use, where the code will run, where credentials will live and whether access survives the session ending.
Understand
I want to use [Codex or Hermes]. Explain the simplest reliable route and any costs or limits.
If you choose Codex
Use a local Codex project on your PC. Follow the eve-inspired architecture guide (opens in a new tab) to organise instructions, skills, tools and tests. Codex performs the work; do not install or deploy eve for this course. Confirm network access, supported skill discovery and private secret storage. Do not put a client secret in browser-side code or a committed project file.
If you choose Hermes
Use the existing non-administrator Hermes account and approved workspace on your VPS. Confirm the installed version, service and tool access. If you use Telegram, keep its existing private-user restriction. Do not give Hermes administrator rights to make Xero work. Both tracks use the Markdown second-brain guide (opens in a new tab): keep source references, setup decisions and reviewed outputs in the approved workspace, without storing credentials or importing private accounting records by default.
Output
Record the chosen environment, sign-in method and recovery plan for my review.
Compare Xero's standard OAuth authorisation-code flow, PKCE for suitable public/native clients, and a Custom Connection only if current eligibility, scope support and price fit. Let current documentation and your environment determine the choice; do not assume one method works everywhere.
Your checkpoint
one destination and one connection method are chosen. You know the cost, who can access the credentials, how authorisation returns to the right machine and what happens when the environment restarts.
Stage 3 of 11
Agree on read and write access
Discover
Map all the relevant accounting read and write capabilities to Xero's current scopes. Show any gaps or restricted endpoints.
Use the accounting access reference below. New Xero apps use granular scopes. “All accounting access” is a business requirement to map, not a literal wildcard to paste into OAuth.
Understand
I want full relevant accounting capability, with changes controlled by approval. Explain what each permission would allow and what should remain blocked.
Review the exact organisation, data categories, scope names and where accounting data would be processed. Include the selected model provider and, if applicable, Telegram. Obtain the associated user's consent before passing API data to a third party, as required by Xero's terms, section 7 (opens in a new tab). Check the chosen provider's no-training controls and retention. Xero prohibits using its API data to train or fine-tune AI models; consent does not override that restriction. Start with fictional data.
Output
Prepare the exact access request and action boundaries for me to approve.
The plan should separate reading, previewing a proposed change and executing it. Broadly capable credentials must sit behind narrow controls. A skill's instruction to “ask first” is not a substitute for a tested write gate in the tool layer. If your chosen environment cannot enforce the boundary, keep writes disabled while you resolve that gap.
Your checkpoint
the scope list covers the agreed accounting work, explains exclusions and names the data destinations. Writes remain disabled until an exact proposed operation has been reviewed and approved.
Stage 4 of 11
Register the Xero app
Discover
Can you use the browser in this app to help set up our Xero connection? Check access, current requirements and Xero's authorisation before acting.
Start with browser assistance in the same ChatGPT conversation. Have ChatGPT identify the browser it would use and check the intended automation is authorised by Xero. Where it is, it can inspect the permitted setup screens and prepare approved non-secret fields. Pause for you at sign-in, credential creation, new agreements and access consent. If either permission or browser control is unavailable, keep the conversation open and follow the manual route below.
Understand
Explain the app details, callback address and access request before I submit them.
Verify the app name, owner, app type and redirect URI. Understand who can change the app and how you will revoke it. Review the current terms and any price before accepting them. Do not select extra products or buy a Custom Connection just to get past an error.
Output
Help complete the approved setup through the available browser. Pause for my secure steps; use a manual checklist wherever automation is unavailable or not authorised.
Manual setup route
- Open developer.xero.com (opens in a new tab) in your browser and sign in yourself with the authorised Xero account
- Open the developer app management area and choose to create a new app; have ChatGPT check the current labels if they differ
- Enter the agreed app name and choose the application type for your approved flow: a confidential web app or the supported mobile/desktop PKCE option; choose a Custom Connection only if that was your reviewed decision
- Enter the legitimate company/application URL requested and, for a redirect-based flow, the exact redirect URI prepared for your environment; a local address on your laptop is not automatically the callback on your VPS. Follow the separate Custom Connection wizard if that is your chosen route
- Review the app details, terms and any charges yourself, then submit the registration only when you agree
- Open the app's configuration; for a confidential app, create its client secret yourself and save it directly to the approved private store; for PKCE, no client secret is issued
- Put the required client identifier and non-secret configuration in the planned settings, then ask ChatGPT to verify the configuration is present without showing credential values
The code should refer to secrets by their configured names. If a screen asks for a different permission, app type or paid product, return to Understand before continuing. Stage 6 completes the organisation connection; registration alone does not grant it.
Your checkpoint
the correct app is registered, its callback or Custom Connection configuration matches the plan, the required configuration is in place and no secret appears in chat, logs or version control. Registration alone has not connected an organisation.
Stage 5 of 11
Build the connection in the target
Discover
Check the official Xero SDKs and agent tools. What can we safely reuse for this environment?
Inspect Xero's official agent toolkit (opens in a new tab), MCP server (opens in a new tab) and prompt library (opens in a new tab) where they fit. MCP is one possible tool connection, not a requirement. Its available tools may cover only part of the accounting scope plan; a supplied bearer token alone does not solve ongoing token refresh. Do not inherit unrelated Payroll permissions from an example. An example or generated skill still needs review and testing. Ask ChatGPT to inspect its dependencies, authentication path, actual endpoint coverage and security controls before installing it.
Understand
Show me the proposed files, permissions and safeguards. What will stop an accidental write or wrong-company request?
The implementation should use the technical checklist below: protected credentials, explicit company selection, read-only default, validated inputs, controlled retries, useful errors and a redacted audit record. Review software installation and any changes to persistent access before they happen.
Output
Build the approved connection in our chosen environment. Keep writes locked and report what is implemented and what is still untested.
Review the proposed work first and give the specific approval needed. Ask ChatGPT to run local tests with fictional fixtures before a real API call. Tests that use mocked responses must be labelled as mocked.
Your checkpoint
the integration exists in the selected project or Hermes workspace, its local tests pass and the runtime can find its configuration without revealing secrets. The write gate is demonstrably closed.
Stage 6 of 11
Authorise the test company and prove the connection
Discover
Walk me through connecting only the approved demo or test company.
Manual authorisation steps
- Ask ChatGPT to start the approved OAuth connection flow from the intended runtime; for a Custom Connection, use its supported organisation-authorisation route
- Open the official Xero authorisation screen and sign in yourself; keep the callback listener ready on the correct machine
- Check the requesting app, select only the approved demo or test organisation, and review the exact access being requested
- Approve the consent yourself only when it matches the plan; new data access or a new destination requires a new decision
- Let the browser return through the registered callback where applicable, then return to this ChatGPT conversation and ask it to check the connection; never paste a code-bearing callback URL into chat
If consent fails or returns to an unexpected address, stop and have ChatGPT diagnose the flow without exposing codes or tokens.
Understand
How will we prove this is the intended company before requesting its accounting data?
For standard OAuth, the integration should retrieve the available connections, display the non-secret company identity and make you choose the intended tenant. Never silently select the first organisation returned. Pin the approved tenant for subsequent requests. A Custom Connection uses its single authorised organisation; verify its identity through the supported route.
Output
Make the first read-only identity check and show me the evidence, with secrets removed.
Record the organisation name, tenant identifier where applicable, currency, country, connection time and granted scope set. Check the Organisation response's IsDemoCompany flag; do not rely on a company name that merely contains “demo”. If using another test organisation, obtain explicit approval for that named organisation and its synthetic records. Check the corresponding organisation in Xero yourself. If anything differs, stop before reading more or writing anything.
Your checkpoint
a real API response identifies the approved test company. Credentials are protected, the tenant guard is active and a request to an unapproved tenant is refused.
Stage 7 of 11
Build reusable accounting skills
Discover
What reusable skills would make this connection useful for my accounting work?
A skill should help the agent choose and perform a task reliably. It needs clear instructions and working tools, plus examples and tests. A Markdown file on its own does not prove the agent can load or execute it.
Understand
Start with reading accounts, preparing draft changes and carrying out an approved change. How will these stay within our boundaries?
Use separate entry points for reading, previewing and approved writing. Keep the credential store outside the material the model needs to read. Let the runtime enforce company, endpoint and approval restrictions. Retain the official sources and date checked with the skill.
Output
Build those skills around our working API connection. Follow the installed agent's current skill format and include examples, tests and clear limits.
For Codex
Have ChatGPT inspect the current project instructions and supported skill discovery path. Install the approved files there. Open a fresh task/session in that same project and verify the skill is discovered and invokes the real integration without pasting its instructions again.
For Hermes
Have ChatGPT inspect the installed version's skill format, loader and workspace. Install under the Hermes account, then open a fresh Hermes session and run the skill there. If you use Telegram, repeat the task through the private bot and verify its process uses the same approved workspace and configuration.
Your checkpoint
the actual target loads the skills in a fresh session and performs a permitted read. A plain-language request outside their permissions is blocked, with an explanation rather than invented results.
Stage 8 of 11
Test reading and accounting judgement
Discover
Suggest a small set of read-only tests for our first accounting task.
Understand
Use [test company], [period] and [currency]. Explain how we will check the result against Xero.
Agree on the expected answer before testing. Choose a bounded request, such as a short list of overdue invoices or a profit and loss report for a known period. Confirm the accounting basis, status filters and whether totals include tax. Do not mix currencies or silently treat missing pages as a complete dataset.
Output
Run the agreed read tests through the skill. Show the source records, assumptions and any uncertainty.
Check record IDs, report dates and retrieval time against Xero. Use a working source link only where one is supported and verified; otherwise provide the record ID and how to find it. Ask one question the retrieved data cannot answer. The agent should say what is missing, rather than make up a financial explanation.
Then try:
Test missing data, a misleading description and a request outside our permissions. Show that the skill handles each safely.
Use harmless fixtures for misleading text. A contact name, invoice description, attachment or API error is data, not permission to follow instructions embedded in it. Minimise real financial data in outputs and logs.
Your checkpoint
results match the expected records or reports, source references resolve, pagination and accounting assumptions are visible, and unsupported conclusions are identified. Any discrepancy is investigated before proceeding.
Stage 9 of 11
Prove one safe write
Specific human approval before executing a write
Discover
Propose one reversible write test using fictional data in our approved test company.
Use a clearly labelled dummy contact and a DRAFT invoice, or a smaller supported draft operation suited to the test company. The test must not send an invoice, authorise or post a journal, record a payment, initiate a transfer or change a real organisation.
Understand
Show me exactly what would change, how we will detect duplicates and how we will clean up.
Review the company, operation, proposed fields, accounting codes, tax, currency and resulting status. Require a before-and-after preview and a unique test marker. Check the endpoint's actual reversal or deletion rules; “undo” is not a universal API feature. Agree separately on cleanup.
Output
Prepare the dry run and exact write request for my approval. Do not execute it yet.
When you understand the preview, approve that specific test operation. The tool must bind the approval to that company, payload and action. If the data changes, the approval must not silently carry over.
After approval, ask:
Run the approved test once, read it back and show whether the stored result matches the preview.
Verify in Xero yourself. Test duplicate protection using the same approved logical operation only where the endpoint and test plan make that safe; use a simulated timeout to test uncertain outcomes without producing extra records. Clean up only the identified test records after the agreed approval.
Your checkpoint
one approved test write is verified by read-back and in Xero, with record ID, timestamp and redacted audit evidence. Unapproved and changed-payload requests are rejected. Cleanup is verified or the retained test record is explicitly documented.
Stage 10 of 11
Test failure and recovery
Discover
What failures could make this connection unsafe or unreliable?
Understand
Which tests can we simulate safely, and which need a real restart or reconnection?
Cover token expiry and refresh, lost authorisation, wrong tenant, invalid data, rate limits, pagination, timeouts and uncertain write results. Test failures with fixtures where possible. Do not flood Xero or revoke live access to demonstrate an error.
Output
Run our approved recovery tests. Label real and simulated evidence, fix failures and repeat the affected checks.
Prove a fresh session can still use the skill and a controlled runtime restart preserves the right configuration. For Hermes, include the service restart and Telegram route if used. Keep a single owner of token refresh per OAuth grant so parallel tasks and organisations sharing that grant do not overwrite rotated credentials. Perform a real refresh and another read after restart for authorisation-code OAuth, including PKCE, or obtain a fresh client-credentials token and read for a Custom Connection. Use simulations for long-expiry and failure cases that cannot be observed during class.
Restore the non-secret code and configuration into an isolated test environment. Handle secrets through the approved private recovery route, and never start a second active worker against the same live workflow by accident. Practise stopping the integration. Confirm how a human disconnects the app and revokes exposed credentials.
Your checkpoint
normal work resumes after the approved restart; safe failure responses, duplicate protection and secret redaction have evidence. Untested token-lifetime or failure cases remain clearly marked. An unresolved safety-critical failure blocks release.
Stage 11 of 11
Review readiness for real accounting work
Discover
Compare our evidence with the acceptance checklist. What is still untested or unsuitable for production?
Understand
Explain the remaining risks so I can decide what to approve with the owner of the books.
Demo success is evidence about a test setup. Real work also needs the right business authorisation, data-processing permissions, accounting judgement and operating controls. Recheck the production organisation's identity, scopes, user role, currency and tax settings. Begin with explicitly approved read-only work.
Output
Prepare a one-page operating record and the evidence for human sign-off.
Record the environment, versions, company, scope decisions, permitted tasks, approval rules, costs, maintenance owner, tests, unresolved issues, stop procedure and recovery steps. Include no secrets. Any first production write needs its own exact preview and approval; a passed demo test never authorises it.
Your checkpoint
you and the responsible instructor or accounting owner review the evidence and set the status: draft, human review, or approved for the stated use case. The AI cannot approve its own work. If an important check is missing, narrow the approved use or keep the integration out of production.
Evidence before approval
Production acceptance
Check every gate against dated evidence. Study checkmarks in the HTML guide are personal progress notes, not access approval or production sign-off.
- Purpose and authority: named accounting owner, selected task, organisation, data destinations and qualified review where needed
- Access and secrets: exact granted scopes, correct tenant guard, human-completed consent, private credential storage and no secret leakage
- Working skills: supported installation, fresh-session discovery, real API invocation in the target and Telegram verification if used
- Read accuracy: expected records and reports, complete pagination, correct period/currency/basis, valid source references and explicit uncertainty
- Controlled writes: dry-run default, enforced approval, exact payload/tenant binding, safe demo write, read-back and duplicate protection
- Adverse cases: wrong tenant, denied scope, missing and malformed input, embedded instructions, revoked access, rate limits and uncertain outcomes
- Recovery and ownership: restart evidence, token-refresh handling, isolated restore, tested stop control, redacted audit trail, costs and maintenance owner
- Human sign-off: dated test record distinguishes real, simulated, passed, failed and untested; approver names the limited production use and accepts any remaining non-critical limitations
Maintain a capability matrix for every requested scope/resource: verified read, verified write, demo-only, unavailable/gated or untested. A draft-invoice test does not prove payments, journals, contacts, settings or other write operations work. Additional writes need their own bounded, approved demo scenarios. For each test, record the target, expected result, actual result, evidence location and reviewer. A HTTP success status alone does not prove accounting correctness. A scope listed in a plan is not proof that it was granted or that its endpoints work.
Supporting reference
Accounting access reference
Open accounting access reference
This section helps ChatGPT build and check the scope plan. Recheck the official sources at setup time. Xero's app type, country, subscription, user role and endpoint restrictions still apply.
Current accounting scopes
New apps created on or after 2 March 2026 use granular scopes. Xero plans to retire the older broad scopes on 13 September 2027. New permissions require fresh consent; refreshing a token does not add them. Sources: Xero granular-scope FAQ (opens in a new tab) and dated changelog (opens in a new tab).
The following unsuffixed accounting scopes provide the relevant read/write capability where the endpoint supports it. They do not guarantee every operation, every user role or every lifecycle state. The report and budget scopes below are read-only.
| Accounting capability | Scope to review | Important boundary |
|---|---|---|
| Invoices, credit notes, quotes, purchase orders, repeating invoices, linked transactions and items | accounting.invoices | Status and endpoint rules determine permitted changes; sending an invoice is a separate action |
| Payments, batch payments, overpayments and prepayments | accounting.payments | Recording or changing payments needs its own accounting approval; no payment test in the basic lesson |
| Bank transactions and bank transfers | accounting.banktransactions | These API capabilities do not give authority to move money or change bank records |
| Manual journals | accounting.manualjournals | Separate from the premium Journals read endpoint; posting requires specific accounting review |
| Accounting settings | accounting.settings | Includes sensitive configuration changes; keep unapproved settings writes blocked |
| Contacts | accounting.contacts | Changes to bank details have additional role restrictions and require specific review |
| Accounting attachments | accounting.attachments | Uploading or retrieving an attachment can expose private data; approve its content and destination |
| Budgets | accounting.budgets.read | Read-only capability |
| Aged reports | accounting.reports.aged.read | Read-only reports; verify period and filters |
| Balance sheet | accounting.reports.balancesheet.read | Read-only reports |
| Bank summary | accounting.reports.banksummary.read | Read-only reports |
| Budget summary | accounting.reports.budgetsummary.read | Read-only reports |
| Executive summary | accounting.reports.executivesummary.read | Read-only reports |
| Profit and loss | accounting.reports.profitandloss.read | Read-only reports |
| Trial balance | accounting.reports.trialbalance.read | Read-only reports |
| Tax reports | accounting.reports.taxreports.read | Country and endpoint restrictions apply; this is not permission to file tax returns |
Add offline_access for refresh tokens in authorisation-code OAuth, including PKCE. Add openid, profile and email only when those identity claims are needed. Custom Connections use their own scope and client-credentials setup; do not copy standard OAuth extras blindly.
Scope inventory source: Xero's official scope reference in its Python prompt-library skill (opens in a new tab). Check it against the live OAuth scopes documentation (opens in a new tab) and actual consent screen during setup. This guide has not validated a live granted token.
Products and endpoints to check separately
accounting.journals.read is optional and gated. General-ledger Journals access requires the qualifying Advanced tier and Xero's assessment/use-case approval. It is distinct from ManualJournals. New Custom Connections created from 29 April 2026 do not include Journals. Do not promise it on the free Starter tier. Sources: Xero pricing (opens in a new tab), Custom Connection FAQ (opens in a new tab).
Payroll, Assets, Projects, Files, Bank Feeds, Finance, Practice Manager and Xero HQ are separate products or APIs to assess if requested. Accounting attachments are not the whole Files API. API coverage is endpoint-specific and need not match everything visible in the Xero interface. Recheck deprecated resources and country-specific operations against the current changelog (opens in a new tab). Never work around a missing permission by switching organisations or using a broader credential.
Connection methods and callback checks
- PKCE: appropriate for a supported public/native client that cannot safely hold a client secret. Xero issues no client secret for this flow. Use S256 and state validation. Xero supports HTTPS callbacks and an HTTP localhost exception, but not custom URI schemes or browser-only single-page apps. Authorisation codes expire after five minutes. Source: Xero PKCE flow (opens in a new tab)
- Standard web-app OAuth: suitable when the backend can protect its client secret and token store. Verify the exact registered scheme, host, port and path. A local callback on the student's computer does not automatically reach the Hermes VPS; choose a supported, reachable callback arrangement. Do not expose a development server publicly without reviewing its security. Sources: OAuth overview (opens in a new tab), OAuth FAQ (opens in a new tab)
- Custom Connection: optional single-organisation server-to-server access, currently offered for Australia, New Zealand, UK and US organisations. It has its own paid per-connection model; demo access is free. It uses client credentials, with no refresh token or tenant header. Ordinary client credentials alone do not grant Accounting API access. Verify the current price and eligibility before choosing it. Sources: Custom development (opens in a new tab), client credentials (opens in a new tab)
For standard OAuth, use the selected tenant from the connections endpoint as the xero-tenant-id header. Never choose the first returned organisation silently. Source: Xero tenants (opens in a new tab).
Token lifecycle and operating limits
For authorisation-code OAuth, including PKCE, access tokens last 30 minutes. An unused refresh token expires after 60 days; each refresh returns a new token pair to save securely and atomically. The previous refresh token has a 30-minute retry grace period, which should not be used as the concurrency design. Source: Xero token types (opens in a new tab).
As checked on 8 October 2026, Starter is free with five connected organisations and 1,000 API calls per organisation per day. Paid tiers, additional products and data egress may add costs. Prefer the current pricing page (opens in a new tab) over older examples claiming 25 free connections.
Current per-organisation limits include five concurrent calls and 60 calls per minute, alongside the daily allowance; app-wide limits also apply. Respect the response headers and Retry-After. Source: Xero rate limits (opens in a new tab).
Xero's supported idempotency keys are retained for six minutes and may be at most 128 characters; a different payload must not reuse the key. Keep your own durable operation record beyond that window, and resolve an uncertain outcome before resending. Source: Xero idempotent requests (opens in a new tab).
For the demo invoice test, use a discovered valid account and tax configuration, set DRAFT explicitly, and verify the stored status. Deletion/voiding rules depend on status. Do not send or approve it. Source: Xero invoice endpoint (opens in a new tab).
Supporting reference
Technical checklist for the implementation
Open technical checklist for the implementation
Use this as an acceptance checklist for the AI's implementation. It does not require you to write the code yourself.
- Authentication: use the chosen supported OAuth flow; exact redirect matching; state validation and PKCE where applicable; protected token storage; safe refresh rotation; no secrets in model context, browser-side code, logs or Git; handle the code-bearing OAuth callback securely and never share or log that URL
- Company boundary: explicitly selected and pinned tenant; validate it on every operation; reject unknown or mismatched tenants; isolate demo and production credentials and configuration
- Action boundary: read-only default; separate read, preview and write tools; allowlisted endpoints and methods; least-privilege runtime; an approval gate outside prompt text; no unrestricted tool that bypasses the gate. If the agent's shell can read raw credentials or invoke arbitrary Xero writes, isolate the credential-bearing client behind a restricted service or tool boundary before enabling writes
- Inputs and accounting: validate schemas, dates, statuses, currency, tax and account codes against that organisation; preserve decimal precision; record accounting basis and time zone; reject ambiguous entities rather than matching the first name
- Writes: show the exact proposed change; bind approval to a stable payload and tenant; require a new review if either changes; read current state before updating; read back after writing; inspect per-record validation errors and partial success
- Retries and duplicates: use Xero's idempotency support only where documented; retain the same key for the same logical request; protect unsupported operations with a persistent operation ledger and reconciliation; never blindly replay a write after a timeout
- Limits and completeness: honour current rate-limit and Retry-After responses; bounded backoff with jitter; cap concurrency; paginate fully; use supported incremental filters; make a partial dataset explicit
- Audit and privacy: capture actor, approval, tenant, operation, timestamp, record IDs, outcome and correlation identifier; redact tokens and unnecessary personal/financial content; set access and retention; treat incoming content as untrusted data
- Maintenance: pin and record tested versions; test dependency updates; document connection limits and costs; monitor failures through an approved route; maintain a stop switch and recovery instructions; never let an alert stand in for a hard limit
- Tests: unit fixtures plus real demo smoke tests; expected accounting results; missing/denied/malformed data; no cross-tenant access; blocked unapproved writes; uncertain outcomes; fresh-session loading; restart and isolated restore
Keep learning
Keep the conversation simple
Use these whenever they help:
Explain that in plain English.
What are you assuming, and what did you verify?
What changed because of my situation?
Show me the evidence before we continue.
I don't understand this yet. Let's stay here.
Stop. Check what actually happened before retrying.
If the gap is a fact, return to Discover. If it is a choice or professional judgement, stay in Understand. If an output changes a decision, review that decision again.
Keep learning
Final student check
Can you explain in your own words:
- Where the connection runs and where its credentials are stored?
- Why API scope, company selection and permission to perform an action are separate?
- How you know a skill really loaded and used the API?
- What makes the accounting answer correct and its source traceable?
- Why an uncertain write must be checked before retrying?
- How you stop access, recover the setup and know which tests remain incomplete?
If not, ask another short question. The lesson is complete when you can make and defend those decisions and the approved use has evidence behind it.
Keep learning
Useful external resources
Open these when you reach the matching step. Start with the guide or overview before the technical reference.
- Developer portal: Xero Developer (opens in a new tab) to register and manage your app during Stage 4
- Choose a connection: OAuth overview (opens in a new tab), PKCE guide (opens in a new tab) and Custom Connections (opens in a new tab) for Stages 2 and 4
- Access and consent: Scope documentation (opens in a new tab) and granular-scope FAQ (opens in a new tab) for Stage 3
- Examples for your agent: Official Xero agent toolkit (opens in a new tab), MCP server (opens in a new tab) and prompt library (opens in a new tab) for Stages 5 and 7
- Your safe write test: Invoice API documentation (opens in a new tab) for Stage 9
- Troubleshoot sign-in: OAuth FAQ (opens in a new tab) and token lifecycle (opens in a new tab) for callback, refresh and reconnect questions
- Troubleshoot requests: Rate limits (opens in a new tab) and safe request retries (opens in a new tab) for Stage 10
- Check costs and changes: Current pricing (opens in a new tab) and Xero developer changelog (opens in a new tab) before approving or updating a setup
- Course foundations: Previous Hermes guide (opens in a new tab) and DUO Framework (opens in a new tab)
Keep learning
Instructor notes and sources
Open instructor notes and sources
Use the live Hermes student guide (opens in a new tab) for prerequisite security and operating practice. This Xero lesson does not repeat VPS provisioning. Let learners choose one target and a small first use case, then bring technical detail into the conversation when it matters.
Do not turn DUO into a compulsory recital. Ask learners to explain a trade-off, challenge a proposed answer and decide whether the evidence is enough. DUO supports qualified professional review; it does not replace responsibility for the books.
Documentation and examples were reviewed on 8 October 2026. The authoritative sources are linked beside the relevant facts above. During class, recheck the current developer terms, pricing, scope documentation and installed software before approving a setup.
Official examples require hardening: Xero's Node OAuth sample (opens in a new tab) warns against using a production organisation for its demo and recommends a proper production datastore. The desktop PKCE example (opens in a new tab) also states that it is not production-ready as supplied.
The guide's tenant locking, approval binding, secret isolation, test sequence and evidence gates are recommended implementation controls. Students must verify that the chosen runtime actually enforces them. A successful sample, consent screen or model response is insufficient evidence on its own.