> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/settings/configuring-integration-sync-and-credentials.md).

# Configuring Integration Sync and Credentials

{% hint style="info" %}
**Path:** `/settings/integrations`
{% endhint %}

### Configuring Sync Settings

#### Understanding Sync Settings

Some integrations support **outbound sync** - sending data from Harmony to the connected system (e.g., creating or updating tickets in Freshservice or SolarWinds). When enabled, Harmony can sync ticket data bidirectionally with the ITSM.

#### Default Sync Settings by ITSM Integration

When you connect an ITSM integration, Harmony automatically applies sensible default sync settings based on the specific tool you are connecting - no manual configuration is required to get started. Each vendor ships with defaults tailored to its typical use case:

| Integration                       | Default Sync Settings                          |
| --------------------------------- | ---------------------------------------------- |
| **ServiceNow**                    | Import, export, and outbound sync all disabled |
| **Jira**                          | Export and outbound sync enabled               |
| **Jira Service Management (JSM)** | Import enabled                                 |
| **Freshservice**                  | Import enabled                                 |
| **SolarWinds**                    | Import enabled                                 |

These defaults are applied automatically the moment the integration is connected. You can adjust them at any time from the integration configuration panel.

#### Configuring Sync Frequency

Sync frequency and schedule are managed by the backend. There is no UI to configure sync interval or timing. Sync runs according to the integration's default or backend configuration.

#### Automatic Sync After Configuration Changes

When you add or update a connected integration, Harmony automatically triggers data collection from the configured third party. This means your MDM, HRIS, and other connected platforms stay in sync without requiring any manual action after setup. Changes to your integrations take effect immediately, triggering the appropriate data flows in the background as soon as the configuration is saved.

#### Understanding Bidirectional Sync

**Bidirectional synchronization** means Harmony and the connected system can both create and update items (e.g., tickets). Data flows from Harmony to the ITSM and, when applicable, from the ITSM back to Harmony. This keeps tickets in sync across systems.

#### Enabling Sync

For integrations that support it (e.g., Freshservice, SolarWinds):

1. Open the integration and complete the connection (subdomain, credentials).
2. Find the **Bidirectional synchronization** toggle in the configuration.
3. Turn the toggle **on** to enable outbound sync.
4. Click **Save Changes** to confirm. The toggle does not apply instantly - your changes take effect only after saving.

{% hint style="info" %}
You can toggle sync on or off alongside other configuration changes (such as switching desks in JSM) and save everything at once. Closing the settings panel without saving will discard any unsaved toggle changes.
{% endhint %}

![Bidirectional sync toggle in integration config](/files/3qCvRJBvJnmy7fssrdlI)

#### Disabling Sync

Turn the **Bidirectional synchronization** toggle **off** and click **Save Changes** to stop Harmony from syncing data to the connected system. Inbound sync (from the ITSM to Harmony) may still occur depending on the integration.

***

### Monitoring Sync Status

#### Understanding Sync Status Indicators

The integration card and modal show **Connected** when the integration has at least one instance. Multi-instance integrations show the instance count. There is no dedicated sync-status indicator (e.g., "Syncing", "Last synced") in the integration settings. Sync runs in the background.

![Integration cards showing Connected state](/files/kQMyWZVwn29H7ZWGVsAN)

#### Viewing Last Sync Time

Last sync time is not displayed in the integration configuration UI. Some areas (e.g., Software Management) may show sync-related timestamps in their own views. Check the connected system or Harmony logs for sync activity if needed.

#### Understanding Sync Progress

Sync progress is not shown in the integration settings. Sync runs asynchronously. If sync fails, check the integration's configuration (credentials, permissions) and reconnect if necessary.

#### Resilient Sync for Customer and Contact Data

Harmony uses permissive parsing when syncing data from connected platforms. Previously, a single unexpected or malformed record could interrupt an entire sync. Now, Harmony processes as much data as possible and skips only records it cannot interpret, rather than halting the sync altogether. This means your customer and contact data stays more consistently up to date, even when source data contains irregularities.

#### Recovery After Provider Outages

Harmony is designed to recover from third-party provider outages without leaving data integrations permanently stuck:

* **Extended retry window** - The maximum number of retries has been increased, giving integrations approximately 11 hours to recover from an outage rather than around 1 hour 15 minutes.
* **Automatic cursor reset** - If a sync poll becomes stuck on a specific failing page (a "poison cursor"), Harmony automatically resets the cursor so the sync can continue from a clean state.

#### Manually Syncing Identity Provider Groups

You can trigger a manual sync of your identity provider (IDP) groups directly from the app access resource creation modal, without waiting for the next scheduled refresh. This makes any recent group changes in your IDP - such as new groups or membership updates - immediately available to select when configuring access.

The sync runs as a tracked background job, so you can see its status and know when the latest group data is ready to use.

#### Troubleshooting Sync Issues

**Common causes of sync failure**

* Invalid or expired credentials
* Insufficient permissions in the connected system
* Network or API errors
* Integration disconnected or misconfigured

**Steps**

1. Verify the integration shows **Connected**.
2. Open the integration and check that credentials are valid (re-enter if needed).
3. Ensure the connected system grants the required permissions (scopes, API access).
4. Disconnect and reconnect the integration to refresh tokens or re-authorize.
5. Check backend logs or support for specific error details.

![Integration modal with credential fields](/files/lda4BD0SZht52lehxTni)

***

### Understanding Integration Permissions

#### Understanding Permission Requirements

Integrations need permission to access the connected system. Requirements depend on the integration:

* **OAuth** - Permissions (scopes) are requested during the authorization flow. The provider shows what Harmony is asking for.
* **Credentials** - API keys, tokens, or admin access may be required. The integration form or documentation lists what you need.

#### Viewing Required Permissions

OAuth integrations request scopes during the connect flow. The provider's authorization screen lists them. There is no separate UI in Harmony to view or modify granted scopes. For credentials-based integrations, required fields are shown in the configuration form (e.g., API key, domain).

#### Managing Permission Grants

* **OAuth** - To change permissions, disconnect and reconnect. You may need to revoke access in the provider first, then reconnect to request new scopes.
* **Credentials** - Update the configuration form and save. New credentials take effect when saved.

#### Understanding Permission Scopes

Scopes define what Harmony can do (e.g., read users, create tickets, list channels). Each integration has predefined scopes. Harmony requests only what it needs. If an integration fails with a permission error, the provider may require additional scopes - reconnect and approve the updated request.

***

### Managing Integration Credentials

#### Understanding Credential Management

Credentials are stored securely by Harmony's backend with encryption at rest, ensuring that sensitive authentication data such as API keys and tokens is protected with an additional layer of security. This applies automatically to all integrations - no action is required on your part.

The UI does not display raw credentials. Passwords, API keys, tokens, and other secrets are obfuscated by default, so only a masked version is shown (`•••`). This reduces the risk of accidentally exposing credentials when sharing your screen, taking screenshots, or granting temporary access to your Settings page. You can update credentials by editing the integration configuration.

#### Labelling Credentials for Easy Identification

You can add an optional label to your integration credentials, making it easier to identify and manage multiple credential sets at a glance. This is especially useful when you have several credentials configured for the same integration type - for example, different accounts, environments, or teams. Simply provide a custom label when creating or updating a credential to keep your integrations organised.

#### Updating Integration Credentials

1. Open the integration (Settings - Integrations - *integration*).
2. For connected instances, configuration may be read-only. To update credentials:
   * If the integration allows post-connection config: edit the fields and click **Save Changes**.
   * If credentials are locked: disconnect and reconnect with new credentials.
3. Enter new values (API key, password, etc.). Password fields support show/hide.
4. Optionally add or update the credential **label** so it remains easy to identify.
5. Save. The new credentials are used for subsequent API calls.

#### Rotating API Keys

There is no dedicated rotation flow in the UI. To rotate an API key:

1. Generate a new key in the connected system.
2. Open the integration configuration.
3. Replace the existing key with the new one and save.
4. Revoke the old key in the connected system after confirming the integration works.

#### Managing OAuth Tokens

OAuth tokens are managed by the backend. The UI does not expose tokens. Refresh happens automatically. If a token expires or is revoked:

* The integration may show as connected but API calls will fail.
* Disconnect and reconnect to obtain a new token.
* In the provider, revoke the old app connection if desired before reconnecting.

#### Credential Security Best Practices

* **Minimal permissions** - Grant only the scopes or access the integration needs.
* **Secure storage** - Credentials are encrypted at rest by Harmony. Do not share them outside the configuration flow.
* **Obfuscation** - Credentials are masked in the UI by default, reducing the risk of accidental exposure.
* **Rotation** - Rotate API keys periodically and when personnel changes.
* **Revocation** - If credentials are compromised, revoke them in the provider and update the integration in Harmony.
* **Access control** - Limit who can view and edit integration settings (via role permissions).
* **Labels** - Use credential labels to clearly distinguish between accounts, environments, or teams, especially in complex workspaces.

***

### Related Resources

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Understanding Integrations</strong></td><td>Integration categories and OAuth</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md</a></td></tr><tr><td><strong>Connecting Integrations</strong></td><td>Connect and configure integrations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/connecting-and-managing-integrations/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/connecting-and-managing-integrations/README.md</a></td></tr><tr><td><strong>Ticket Settings</strong></td><td>Notification channels use integrations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-ticket-settings/README.md</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/settings/configuring-integration-sync-and-credentials.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.