This document explains why and how to reconnect an integration.
Sometimes customers change integration authentication details, API keys expire, or other integration setup details are changed and Kombo can no longer authenticate with an integration that was previously connected.
After three consecutive days of failing authentication (which we check before every sync), Kombo will pause scheduling syncs and will prompt you to reconnect the integration.
Authentication issues can be identified in two ways: programmatically (recommended) or operationally via the Kombo dashboard.
Programmatically:
Use the Integration State Changed webhook. This webhook allows you to monitor changes in the state
value, helping you quickly detect authentication-related issues.
Operationally: Navigate to the Integration page in the Kombo dashboard to review the current state information for a specific integration.
By leveraging these approaches, you can promptly diagnose and address authentication challenges.
If you want to update which data you’re interacting with in your customer’s HR systems, you will likely need to update your Kombo scope config. Updating your scope config in Kombo will usually go hand in hand with your customer having to update their API credentials. Therefore, expanding your scope config will likely end up with syncs showing warnings that not all permissions are granted to the API credentials.
Syncs failing due to scope-mismatches can be avoided by using reconnection links, as described below.
In the Kombo dashboard, navigate to any integration that you want to reconnect. Scroll down to the Relink integration section to create an update link.
You can send this link to your customer to update the credentials of the integration. Once they have reconnected successfully, syncs will run using the newly entered credentials.
You can also create a reconnection link using the create reconnection link endpoint.
Specify the link_type
for it to be used either in the embedded flow,
or sent out as a magic link.
You are able to define the scope config of a reconnection link both in the UI and using the API.
Setting a different scope config than the current integration’s scope config results in the following:
Use this functionality to smoothly migrate your customers to a new scope config, without running into any sync issues. While the reconnection link has not been completed, syncs will continue successfully working using the old scope config; the new scope config will only be used once the reconnection link has been completed.