How to Get Xero API Access (and Why There Is No Simple API Key)

Xero does not issue a simple API key

Most people arrive at this looking for a single key to copy out of Xero settings, the way several other platforms work. Xero does not do that. It uses OAuth 2.0, which means you register an application with Xero and receive a client id and client secret, then exchange those for an access token that your integration uses on each request.

That sounds like extra work, and it is, but the reason is worth understanding. A single permanent key that can read and write your entire ledger is a large risk if it leaks. OAuth tokens are scoped to specific permissions and expire on their own.

Which app type you need

Xero offers different app types, and picking the wrong one wastes a lot of time. In plain terms:

• Custom Connection, for connecting a single Xero organisation, usually your own. This is the right choice for the large majority of businesses. It is a machine to machine connection with no login screen, and it requires a paid Xero subscription.
• Standard app, for software that other businesses will connect their own Xero to. This is what you build if you are shipping a product, not connecting your own books.
• Partner app, a certified Standard app that has been through Xero review, needed once you are serving connections at volume.

If your goal is "get our job management system talking to our Xero", you want a Custom Connection. If your goal is "let our customers connect their Xero to our product", you want a Standard app.

Getting access, step by step

1. Sign in to the Xero developer portal with the same account that has access to the Xero organisation you want to connect.
2. Create a new app and choose the app type from the section above.
3. Record the client id and client secret. The secret is shown once. Treat it like a password and store it somewhere your team can retrieve it safely.
4. Authorise the connection to the specific Xero organisation, and select the scopes the integration needs. Grant only what it will use.
5. Exchange the credentials for an access token, which is what your integration sends with each API call.

What the Xero API lets you do

The Accounting API covers the parts of Xero most integrations need:

• Invoices and bills, create, read and update sales invoices and supplier bills
• Contacts, sync customers and suppliers with a CRM or job system
• Payments and credit notes, including allocation against invoices
• Items, accounts and tax rates, so line items land against the right codes
• Bank transactions and reconciliation data
• Tracking categories, useful for per site, per team or per project reporting

Separate APIs cover Payroll, Files, Projects and Assets. They are not part of the Accounting API, which surprises people who assume one connection covers everything. If your project involves timesheets or pay runs, you are dealing with the Payroll API and its own permissions.

Rate limits and the 30 minute token

Two things catch out most first integrations.

Access tokens are short lived. A Xero access token expires in about half an hour. Your integration has to use the refresh token to obtain a new one automatically, and it has to store the updated refresh token each time, because it changes. Integrations that skip this work perfectly in testing and then stop overnight.

Rate limits are per organisation. Xero applies both a per minute and a daily cap on API calls for each connected organisation. A first sync that loops through several years of invoices one at a time will hit the limit and start receiving errors. Bulk operations need batching, paging and a backoff strategy from the start.

When to bring in a developer

Not every Xero connection needs a build. An honest split:

The API itself is well documented and pleasant to work with. The cost sits in the mapping decisions, the edge cases and the monitoring, which is true of every accounting integration and is why they are worth doing properly the first time.