At a glance
- Availability: Experimental (how to enable).
- Auth: OAuth 2.0.
- Connection: A user authorizes the connection in the provider’s consent screen.
- Scopes:
offline_access,accounting.transactions,accounting.contacts,accounting.settings,accounting.attachments. - Docs: https://developer.xero.com/documentation/guides/oauth2/auth-flow/
Credentials
Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.Setup
- Create a Xero account: Sign up at https://www.xero.com/ - every Xero login includes the free Demo Company, which is ideal for testing API calls without touching real books.
- Create an app in the Xero developer portal: Go to https://developer.xero.com/app/manage and create a new app (Web app type). Set the redirect URI to your app’s /api/auth/xero/callback URL.
- Copy credentials: Copy the Client ID and generate a Client Secret from the app’s Configuration page. Set XERO_CLIENT_ID and XERO_CLIENT_SECRET in your .env.
- Connect and discover your tenant: Complete the OAuth flow, then run the List Connections tool. Copy the tenantId from the response - every other Xero tool requires it as the tenant_id parameter (sent as the xero-tenant-id header).
- The offline_access scope is required - without it Xero issues no refresh token and access expires after 30 minutes
- Refresh tokens are single-use and expire after 60 days of inactivity
- The token endpoint authenticates with HTTP Basic (client_id:client_secret base64-encoded)
- Every Accounting API call must include the xero-tenant-id header; use List Connections to find it
- The accounting.attachments scope is required for the Create Invoice Attachment tool; attachment bodies are raw file bytes (max 10 MB)
- Uncertified apps are limited to 25 connected organisations
Tools
| Tool | Access | Description |
|---|---|---|
| List Connections | Read | List Xero tenants (organisations) connected to this token - run this first to discover the tenantId used by every other tool |
| List Invoices | Read | List invoices in a Xero organisation |
| Get Invoice | Read | Get a Xero sales invoice or supplier bill with its line items |
| Create Invoice | Write | Create an invoice in a Xero organisation |
| List Bills | Read | List supplier bills (accounts payable) in a Xero organisation - bills are Invoices with Type ACCPAY |
| Create Bill | Write | Create a supplier bill (accounts payable) in a Xero organisation - a bill is an Invoice with Type “ACCPAY” |
| Create Invoice Attachment | Write | Attach a file to a Xero sales invoice or supplier bill (max 10 MB per attachment) |
| Create Purchase Order | Write | Create a purchase order in a Xero organisation |
| List Contacts | Read | List contacts in a Xero organisation |
| List Accounts | Read | List the chart of accounts in a Xero organisation |
| List Invoice Attachments | Read | List the attachments on an invoice or bill (AttachmentID, FileName, MimeType, ContentLength) - see what Create Invoice Attachment uploaded |
| List Purchase Orders | Read | List purchase orders in a Xero organisation - the read counterpart to Create Purchase Order |
Example prompts
- List my Xero invoices that are overdue, with amounts due and contact names.
- Create a draft sales invoice in Xero for a contact with the line items I provide.