How to create a Xero API key (Custom Connection)
A Xero Custom Connection gives a single tool or developer programmatic, machine-to-machine access to one Xero organisation. Instead of a person logging in, the connected tool authenticates with a client id and client secret (a matched pair of credentials, the secret being the sensitive half) and requests a short-lived access token to read your data through the Xero API. You choose exactly which scopes the connection has, so you can keep it read-only, and the connection is tied to just one organisation. Nothing in your books changes when you create it, and you can deactivate, delete, or re-issue the credentials at any time, which immediately cuts off access. This guide walks through creating a Custom Connection, selecting read scopes, copying the client id and secret safely, and removing the connection when it is no longer needed. Custom Connections are a premium feature, so a paid Xero subscription and a small per-connection charge apply.
Keep this credential safe
A client id and client secret are like a username and password for your data: anyone who has them can read everything the granted scopes allow, on your behalf, without logging in. Keep them safe. Scope the connection to read-only access where the product allows, tick only the read scopes the tool actually needs, and never grant write or payroll scopes unless they are genuinely required. Share the credentials only through a secure method such as a password-manager share link, not plaintext email or chat. Copy the client secret the moment Xero shows it, because it is displayed only once. When the connection is no longer needed, delete it; if a secret may have been exposed, rotate it by generating a new one, which invalidates the old secret immediately.
Access to grant
OAuth 2.0 Custom Connection (client credentials grant): a client id and client secret pair, restricted to read-only scopes such as accounting.contacts.read, accounting.settings.read, accounting.reports.read, plus the relevant granular read scopes (for example accounting.invoices.read and accounting.banktransactions.read). Connected to one organisation only.
Who you're granting access to
- The developer, consultant, or tool that will read your data through the Xero API.
Before you start
- A Xero login with the Standard or Adviser user role in the organisation you want to connect (this person authorises the connection).
- A paid Xero subscription. Custom Connections are a premium add-on with a recurring per-connection charge, and they are available to organisations in Australia, New Zealand, the United Kingdom, and the United States only.
- A free Xero developer account to access the developer portal at developer.xero.com.
- A secure way to share the client id and client secret with the tool or developer who will use them, such as a password-manager share link.
Step by step
- 1
Sign in to the Xero developer portal
Go to developer.xero.com and sign in with your Xero account (or create a free developer login, which uses your existing Xero credentials). Open the "My Apps" area, which lists any apps and connections you have already created.
- 2
Create a new Custom Connection
Click "New app". Give the app a name, then choose "Custom Connection" as the integration type. Custom Connection is the cleanest option when a single tool needs to read just one organisation, because Xero handles the authorisation for you and there are no refresh tokens to manage. Read and agree to the terms, then click "Create app".
- 3
Select read-only scopes
On the connection settings, choose the scopes the tool is allowed to use, and tick read scopes only. For accounting data that typically means accounting.contacts.read, accounting.settings.read, accounting.reports.read, and the granular read scopes you actually need, such as accounting.invoices.read and accounting.banktransactions.read. Scopes are additive, so add only what the tool genuinely requires. For apps created from 2 March 2026 onward, Xero uses granular scopes, so pick the specific read scopes rather than a single broad one. Leave out any write or payroll scopes unless they have been agreed.
- 4
Set the authorising user and authorise the connection
Choose the authorising user, which must be a Standard or Adviser level user in the target organisation, then authorise the connection. Xero shows a consent screen listing the requested scopes and asks you to confirm the organisation to connect. Confirm to link the connection to that single organisation. Because this is a premium feature, you will be prompted to start the paid per-connection subscription.
- 5
Generate the client secret
Open the connection and copy the client id, which is shown on the configuration page. Then click "Generate a secret" to create the client secret. Copy the secret straight away and store it somewhere safe, because Xero shows the full client secret only once and you cannot view it again afterwards. If you lose it, you have to generate a new one.
- 6
Share the credentials securely and confirm read-only access
Hand the client id and client secret to the developer or tool using a secure method such as a password-manager share link, never plaintext email or chat. Treat the client secret like a password, because anyone who has the id and secret can pull the data those scopes allow. Once configured, the tool can request an access token and read your Xero data within the scopes you granted, and nothing else.
Removing access afterwards
- Sign in to developer.xero.com and open "My Apps".
- Open the Custom Connection you want to change.
- To rotate the secret, click "Generate a secret" again. The previous secret stops working immediately, so update the tool with the new one.
- To revoke access entirely, delete the Custom Connection (or remove the organisation connection). Access ends straight away, and deleting the connection also stops the per-connection charge.
If that option is not available
If you do not have a paid Xero subscription or a Standard/Adviser login, ask the person who manages the Xero subscription to create the Custom Connection and pass you the credentials securely. If a Custom Connection is not suitable, a developer can instead build a standard OAuth 2.0 app (authorisation code flow), which works on any plan and lets a person sign in to grant access, though it requires managing refresh tokens and can connect to more than one organisation. As a last resort for a one-off review, you can grant a read-only Xero user instead of an API credential and share your screen rather than handing over any key.
Frequently Asked Questions
Yes. Custom Connections are a premium feature with a recurring per-connection charge (around $10 AUD per month per connection, with similar amounts in other supported currencies), so a paid Xero subscription is required. They are available to organisations in Australia, New Zealand, the United Kingdom, and the United States only. Deleting the connection stops the charge.
Treat the client secret like a password, because anyone with both the client id and secret can read the data the scopes allow. Share them only through a secure method such as a password-manager share link, never in plaintext email or chat. Copy the secret immediately when Xero displays it, since it is shown only once. Grant read-only scopes only, and delete or rotate the credentials when they are no longer needed.
Yes. When you select scopes, tick read scopes only, such as accounting.contacts.read, accounting.settings.read, accounting.reports.read, and the granular read scopes you need like accounting.invoices.read. Scopes are additive, so the connection can only do what you tick. Leave out any write or payroll scopes so the tool can view your data but not change it.
Sign in to developer.xero.com, open My Apps, and select the Custom Connection. To rotate, click "Generate a secret" to issue a new secret, which immediately invalidates the old one (then update the tool). To revoke access completely, delete the Custom Connection. Access ends straight away.
No. Each Custom Connection is tied to a single organisation. If a tool needs to read more than one organisation, you create a separate Custom Connection for each, or use a standard OAuth 2.0 app, which can connect to multiple organisations through the authorisation code flow.
The person who authorises the Custom Connection must have the Standard or Adviser user role in the organisation being connected. Once it is set up, the client id and secret are what the tool uses, so the authorising person does not need to stay involved day to day.
A Custom Connection is machine-to-machine: it uses the client credentials grant, connects to one organisation, needs no sign-in flow or refresh tokens, and is a paid feature. A standard OAuth 2.0 app uses the authorisation code flow, where a person signs in to grant access, can connect to multiple organisations, requires managing refresh tokens, and works on any plan. Custom Connection is the cleanest route when one tool needs to read one organisation.
Related guides
Steps last checked against Xero on 2026-06-09.
Based on official Xero documentation: Xero Developer: Custom Connections, Xero Developer: Client Credentials, Xero Developer: OAuth 2.0 scopes, Xero Developer: Custom Integration FAQs, Xero Developer: Granular Scopes FAQs. Xero is a trademark of its respective owner; this guide is independent and for instruction only.
Want this handled for you?
Clever Ops connects and automates the systems mid-market businesses already run. Book a free assessment and we will map your stack.