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.
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. New custom connections will use the newly released granular scopes. More information is available here.
Will you support long lived access tokens?
No, we've implemented short-lived tokens with long-lived authorizations as is best practice for OAuth 2.0. All Xero access tokens expire after 30 minutes. Refresh tokens allow your app to obtain new access tokens without involving a user again. Alternatively, if you'd prefer not to have to manage a refresh token, you might be interested in the premium, Custom Connection option. It utilises the client credentials grant type and only requires your client id and client secret to request new access tokens.
Will you support the client credentials grant type?
Yes, using the Client Credentials grant type provides an alternative way to retrieve information about your connections and users' subscriptions, without requiring the user's access or refresh tokens. You will however need a ClientID and a Client Secret.