Custom Integration
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.
Can I access journals with a custom connection?
It depends on when you created your connection.
Connections created before 29 April 2026: These have broad scopes and can continue to access journals using the accounting.journals.read scope.
Connections created from 29 April 2026: these use new granular scopes, which don't include journal access.
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. You'll now use granular scopes for custom connections. More information is available here.
However, if you remove a broad scope from an existing connection, you won't be able to re-add it. Any broad scope you remove will be permanently replaced by granular scopes. You can continue to use your existing broad scopes until September 2027, as long as they remain in your configuration.
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.
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 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.
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.
How do I build a machine to machine integration?
If the organisation you're connecting to is in Australia, New Zealand, the UK or the US then you have the option of utilising our premium integration option Custom Connections.
If your organisation isn't in one of those regions, or you don't want to pay for a Custom Connection, then you can still make use of Web or PKCE code flow for building machine to machine integrations but you'll need to request your tokens and handle authorisation outside off your application.