# Xero setup for PopMCP

You paste the Client id and a freshly generated Client secret from a Xero Web app you create in the Xero Developer portal.

- Auth: OAuth authorization
- Setup time: 5 min
- API base URL: https://api.xero.com/api.xro/2.0
- Credentials screen: https://developer.xero.com/app/manage
- Provider docs: https://developer.xero.com/documentation/guides/oauth2/auth-flow/

## Approval required before this works

Xero issues OAuth 2.0 client credentials instantly and an uncertified app can read and write real organisation data on day one - but it is hard-capped at 25 connected tenants (5 on the free Starter tier), and Xero must formally certify the app against published checkpoints before it can pass that cap, list on the Xero App Store, or move to the paid Plus tier and above.

- Typical wait: Xero publishes no SLA for certification. The gate is commercial as much as clerical: Xero's own 'Building and growing your app' guide says the review step checks you have built Sign Up with Xero and have ten active customer connections, then a Xero developer evangelist works through the certification checkpoints with you. Elapsed time is therefore driven mostly by how long you take to onboard those ten customers and clear rework. Xero states no review turnaround anywhere in its docs - treat any specific figure quoted elsewhere as unofficial. The security self-assessment is a separate step with no published turnaround either; Xero sends it to you at 800 connections or when you request Practice Manager access.
- Cost: Applying for certification is free. Xero's published developer pricing (developer.xero.com/pricing, tiers taking effect 2 March 2026, prices AUD and tax exclusive): Starter free, max 5 connections, no payment method needed; Core $35 AUD/month, max 50 connections, no certification required; Plus $245 AUD/month, max 1,000 connections, certification required; Advanced $1,445 AUD/month, max 10,000 connections, certification plus an initial and annual security assessment; Enterprise price on application, no connection limit and App Store listing mandatory. Egress above the tier allotment (10/50/250 GB on Core/Plus/Advanced) is $2.40 AUD per GB; ingress is unlimited. Custom Connections are a separate paid per-connection subscription that the Xero customer buys for their own organisation.
- Blocked until approved: Nothing on day one for a single-org or small deployment: an uncertified app authenticates and reads/writes live data immediately. What is blocked is scale and premium surface area. Connections: the free Starter tier caps at 5 connections, and Xero's connections guide caps uncertified apps at 25 unique tenants overall - beyond the cap, new tenant authorisations are refused. A second, sharper limit bites per customer: any one Xero organisation may connect to at most 2 uncertified apps, so a prospect who already has two uncertified integrations cannot connect yours at all until you are certified. Certification is also the prerequisite for the Plus tier and above, for a Xero App Store listing (checkpoint 2 requires Plus tier or higher), and for Rapid Sync (lifted API limits for the first 30 minutes of a new connection), which is Not Included on Starter and Core. The Journals endpoint, the Xero Practice Manager (XPM) API and Bulk Connections are Advanced-tier only and additionally require the security assessment plus use-case approval. Separately, until you pass the security self-assessment your connection count is capped at 999 and XPM/Xero HQ APIs stay closed. Rate limits are tier-based rather than certification-based: 1,000 API calls per day per org on Starter versus 5,000 on Core and above.
- Works meanwhile: Everything for a single-org or small-scale integration. Create the app in My Apps, get client_id/client_secret immediately, run the full OAuth 2.0 authorization code or PKCE flow, and call the Accounting, Payroll and Files APIs against real organisations right away - or against the free Xero Demo Company for development. Custom Connections (client credentials, one organisation, no certification) are a supported production route for a machine-to-machine integration with a single customer.

## Before you begin

- Xero login with access to at least one organisation. The free Demo Company works for testing.
- No developer programme signup or app review is needed. A private Web app can connect up to 25 organisations.
- Adviser or Standard access on the organisation you want to authorise

## Get your credentials

### 1. Open My Apps in the Xero Developer portal

Go to https://developer.xero.com/app/manage and sign in with your normal Xero login.

Screen: https://developer.xero.com/app/manage

### 2. Create a Web app

Click New app, enter an App name, and choose Web app as the Integration type. Add your Company or application URL, paste PopMCP's callback into Redirect URI, tick the terms box and click Create app.

Screen: https://developer.xero.com/app/manage

### 3. Reveal the Client id

Open the app and click Configuration in the left pane. Click the eye icon beside Client id and copy the value into PopMCP's Client ID field.

Screen: https://developer.xero.com/app/manage

### 4. Generate a Client secret

On the same Configuration page click Generate a secret. Copy the value from the Client secret 1 box before you leave the page.

Screen: https://developer.xero.com/app/manage

### 5. Connect in PopMCP and choose the organisation

Paste both values into PopMCP and click connect. On Xero's consent screen pick the organisation and click Allow access.

## Fields PopMCP asks for

- Auth type (connectionType): Create an app at developer.xero.com → "New app" → choose "Web app". The OAuth flow keeps your Xero login on Xero's side.
- Client ID (clientId) [required]: Your app's "Client id" from the Configuration tab on developer.xero.com.
- Client secret (clientSecret) [required]: Generate a "Client secret" on your app's Configuration tab. Stored encrypted; used server-side only and never shown again.

## Callback URL to register

https://app.popmcp.com/api/providers/xero/callback

## Scopes requested

- openid
- profile
- email
- offline_access
- accounting.transactions
- accounting.contacts
- accounting.settings
- accounting.journals.read
- accounting.reports.read
- accounting.reports.tenninetynine.read
- accounting.budgets.read
- accounting.attachments
- payroll.employees
- payroll.payruns
- payroll.payslip
- payroll.timesheets
- payroll.settings
- files
- assets
- projects

## Verify

PopMCP shows the Xero connection as Connected and names the authorised organisation. A contacts or invoices call returns rows from that organisation.

## Troubleshooting

### unauthorized_client or redirect_uri mismatch on the consent screen

Cause: The Redirect URI on the app's Configuration page does not exactly match PopMCP's callback.

Fix: Copy the callback from PopMCP, paste it into Configuration, then Redirect URIs, and click Save.

### You lost the client secret

Cause: Xero shows a secret once and never again.

Fix: Open the app's Configuration page, click Generate a secret, and paste the new value into PopMCP. Delete the old secret afterwards.

### invalid_grant when the connection refreshes

Cause: offline_access was not requested, or the refresh token went unused for 60 days.

Fix: Reconnect from PopMCP so a new refresh token is issued.

### 403 on payroll or projects endpoints

Cause: That Xero product is not enabled on the organisation, or the scope was not consented.

Fix: Enable the product in Xero, then reconnect so consent is granted again.

### 429 Too Many Requests

Cause: Over 60 calls in a minute or 5,000 in a day for that organisation.

Fix: Wait for the period named in the Retry-After header. The X-MinLimit-Remaining and X-DayLimit-Remaining headers show what is left.

---

Source: https://www.docs.popmcp.com/docs/integrations/xero/