​
When to reconnect an integration

​
Authentication issues

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.

​
How to Identify Authentication Issues

Authentication issues can be identified in two ways: programmatically (recommended) or operationally via the Kombo dashboard.
  1. 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.
  2. 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.

​
Changes in data scope

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.

​
Methods of reconnecting

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.
image
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.

​
A note on updating the scope config

You are able to define the scope config of a reconnection link both in the UI and using the API.
image
Setting a different scope config than the current integration’s scope config results in the following:
  • Your customer will see the updated scope config in the connection flow (i.e., they will have to create credentials with the newly desired permissions)
  • On connection flow completion, the scope config of the integration will automatically be updated to reflect the new scope config
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.