Introducing Custom Connections
Custom Connections is a new, premium option for building integrations to individual Xero organisations. Now available to Xero organisations in AU, NZ and UK.
Alongside our standard OAuth 2.0 flow, Custom Connections is a streamlined integration option for 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 to build and manage custom integrations.
Key information
- Price: $10/m AUD (inc GST), $10/m NZD (ex GST), £5/m GBP (ex VAT). Recurring monthly subscriber charge for lifetime of custom connection.
- Availability: Xero organisations in AU, NZ and UK only.
- OAuth 1.0a: we’ll continue supporting existing private apps only until 30 September 2021.
- Developer documentation
- Information for Xero users
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.
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: Xero subscribers remain in control of their data, consent is as clear and robust as connecting apps from Xero’s marketplace.
Getting started
Keen to see exactly how they work? Check out this walk-through.
FAQs
Do I need to write code to handle the authorisation flow?
No. When you create a custom connection on developer.xero.com you specify the email address of the authorising user. That user will receive an email which guides them through the authorisation process.
If you are building an integration to an organisation you have access to (e.g. for your own company) then you can also be the authorising user.
Will a Custom Connection require the use of scopes?
Yes. Scopes will be selected when a custom connection is created and displayed to the authorising 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 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?
No, each organisation can only have one custom connection. This won’t affect the uncertified app limit. So an org can have 1 custom connection plus 2 uncertified apps.
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?
