Custom Connections is a premium option for building integrations to individual Xero organisations. It's available to Xero organisations in AU, NZ, UK and now the US. See developer documentation.
Alongside our standard OAuth 2.0 flow, Custom Connections is a streamlined integration option for anyone building bespoke solutions for Xero businesses. It utilises the client credentials grant type to provide a simplified, more efficient developer experience, perfect for machine to machine integrations.
Custom Connections strip away much of the complexity that comes with connecting a traditional app to the Xero API, making it easier for developers and app owners to build and manage custom apps.
For a small monthly fee, Xero organisations in AU, NZ, UK and US can purchase premium access to Xero’s APIs. Enabling them to create (or commission a third party developers to build) secure, seamless and more efficient integrations for their business.
Key information
Price: $10/m AUD (inc GST), $10/m NZD (ex GST), £5/m GBP (ex VAT), $5/m USD (ex tax). Recurring monthly subscriber charge per Custom connection purchased.
Availability: Xero organisations in AU, NZ, UK and US only.
Custom Connections benefits for developers
Simple, fast and secure access: makes it easier to retrieve access tokens and call the API. No need to build an authorization flow into your app (we take care of that).
Goodbye refresh tokens: forget managing refresh tokens for a single integration. Simply use your client id and client secret to request a new access token when you need one.
World class authorisation and consent: a clear, robust user experience that keeps users in control of their data.
More jobs, happier customers: by reducing the complexity to build and manage machine-to-machine (M2M) integrations, you will reduce cost and friction for your customers.
Build more and without limits: owners can purchase as many connections as their business needs - empowering them to innovate more, and you to build and connect countless solutions for their business.
Benefits for Xero businesses and accounting practices
Simple, fast connections: you, or a developer you commission, can access Xero’s APIs and manage custom integrations more easily.
Cost efficient: less complexity and time to build will reduce development costs. Plus, a more efficient connection will save you maintenance and management costs over time.
Highly secure: You remain in control of your data, consent is as clear and robust as connecting apps from Xero’s App Store. More solutions, no limits: purchase as many connections as your business needs - empowering you to innovate, build and connect countless bespoke solutions for your business.
Technical details
Steps to create a custom connection:
A Xero user purchases Custom Connections for their organisation
The developer creates a new Custom connection app on developer.xero.com
The developer requests authorisation from the Xero user
The Xero user grants authorisation to connect to their organisation
The custom connection is activated
If a developer is building an integration to their own organisation then the developer and Xero user will be the same person.
Technical FAQs
Do I need to write code to handle the authorisation flow?
No. When the developer creates a custom connection on developer.xero.com they will specify the email address of the authorising user (e.g. their client). That user will receive an email which guides them through the authorisation process.
If the developer is building an integration to an organization they have access to (e.g. for their own company) they can also be the authorising user.
Will a Custom Connection require the use of scopes?
Yes. Scopes will be selected by the developer when a custom connection is created and displayed to the Xero user during authorisation.
Do I need to specify the xero-tenant-id header when making API calls?
No, the xero-tenant-id header is not required. Each custom connection can only make calls against one organisation so only the access token is required.
Do access tokens expire?
Yes access tokens expire after 30 minutes but a new access token can be requested (as above) without user interaction.
Do I need to manage refresh tokens?
No, refresh tokens are not required. An access token can be requested using only the client_id and client_secret.
Can a custom connection be connected to multiple organisations?
No, it can only be connected to a single organisation.
Can an organisation have multiple custom connections?
Yes, organisations can purchase a Custom Connection for each app they’d like to connect. This won't affect the uncertified app limit. So an org can have 2 uncertified apps plus as many custom connection apps as needed.
Will I still be able to build a custom integration for free?
Yes. You’ll still be able to build to the standard OAuth 2.0 flow if you prefer. Regular OAuth 2.0 apps will remain free to create and use. Or, if you have a native app, PKCE makes it quick and easy for mobile and desktop app developers to build directly to the Xero API with no need to build a comms proxy or manage private app credentials for every connection.
How can I test a Custom Connection?
Custom Connections can be tested using the demo company. There is no charge when using a demo company.
Can I make changes to a custom connection after it’s activated? Can I add more scopes or switch organisations?
Yes. If you choose to make changes to your custom connection it will be deactivated until it is re-authorised.
Still have questions?