> 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/connecting-and-managing-integrations.md).

# Connecting and Managing Integrations

Learn how to connect, configure, and manage Harmony integrations-including multi-instance integrations and disconnecting.

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

### Connecting Your First Integration

#### Prerequisites for Integration

Prerequisites depend on the integration type:

**Form-based (credentials)**

* Prepare the required values (domain, API key, client ID/secret, etc.). The integration card or setup flow lists what you need.
* **Okta** - Set up an app in the Okta Admin Console or Okta Integration Network, then provide **Client ID**, **Client secret**, and **Okta domain**.

**OAuth**

* No credentials to enter. You sign in to the provider and approve Harmony's access. Multi-instance cards still ask for an **Instance name**, and some cards ask for a **Region**.
* Ensure you have admin access if the provider requires it (e.g., Slack workspace admin).
* Some OAuth integrations can be connected a limited number of times. If every instance is used, you'll see "Maximum number of instances reached" and must delete an instance before adding another.

#### Integration Setup Process

1. Go to **Settings** → **Integrations**.
2. Find the integration under its category, or search for it by name, and click its card. Cards have no **Connect** button; the card opens the integration's setup window. Some integrations are offered only in some hosting regions or only on some accounts; if you can't find a card, contact Harmony support.
3. Complete the flow for your integration type:
   * **Form-based** - Fill in the configuration form (domain, credentials, etc.) and click **Connect**.
   * **OAuth** - Click **Connect**, sign in to the provider and approve the permissions. If the integration needs more settings, fill them in when you return to Harmony and click **Complete Configuration**.
   * **Multi-instance** - Enter an **Instance name** first. It is required. See [Using Multi-Instance Integrations](#using-multi-instance-integrations).

![Settings > Integrations with integration cards](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-470e8378b6cbb525c01307c9a5f1d65fb6c7f203%2Fintegrations-connect.png?alt=media)

#### Authorizing Integration Access

For OAuth integrations, the provider's authorization page opens in the same browser tab and returns you to Harmony when you finish (Slack opens it in a popup). You grant Harmony permission to access the service (users, channels, data, etc.). Harmony does not control the permission list; it is defined by the integration and provider.

#### Granting Permissions

Review the requested permissions on the provider's screen. Approve them to complete the connection. Without approval, the connection fails. Some providers require an admin to approve.

#### Completing Connection

* **Form-based** - After you click **Connect**, a success toast appears and the modal closes. A few integrations keep the window open for a next step, such as choosing what to sync or following installation instructions.
* **OAuth** - After you approve on the provider's page, you return to Harmony, a success toast appears, and the integration list refreshes.
* **OAuth with additional settings** - After you approve, Harmony shows "OAuth authentication completed successfully. Please provide the following configuration details to complete the connection." Fill in the fields and click **Complete Configuration** to finish the connection.

***

### Configuring Integration Settings

#### Understanding Integration Configuration

Configuration is driven by the backend. Each integration defines **configuration fields** (e.g., text, password, select, textarea, file, email, URL). Some integrations use **plugins** that add custom UI (e.g., Confluence space picker, subdomain input for Freshservice/SolarWinds).

When you open a setup modal for a supported integration, a **"For more details, visit our documentation ↗"** link appears at the top of the configuration panel. Clicking it takes you directly to the relevant docs page for that integration, so the right reference is always available without switching tabs or searching separately. This link is available across both single-instance and multi-instance integration modals.

#### Configuring Integration Options

1. Open the integration (click the card or use the connect modal for a connected integration).
2. Edit the configuration fields as needed.
3. For plugins (e.g., Confluence), use the extended UI (space selection, subdomain) to set options.
4. Click **Save Changes** when done (on a multi-instance card, **Save changes** on the instance's row).

#### Setting Integration Preferences

* **Required fields** - Must be filled before saving.
* **Validation** - Fields may have pattern or format checks. Errors appear on blur after a failed submit.
* **Passwords/secrets** - Shown masked (`•••`) once saved. Harmony never displays a stored secret again: the visibility toggle shows only the masked value. Where an integration lets you change a secret after connecting, click **Replace** beside it and paste the new value; otherwise disconnect and connect again with the new credentials.
* **URL fields** - Harmony automatically corrects common URL formatting issues across all integration configuration forms. URLs entered without `https://` are automatically prefixed, trailing slashes are normalized, and partial URLs (e.g., `yourcompany.api.kandji.io`) are expanded to a valid full URL. You do not need to worry about getting the exact format right.

#### Post-Connection Configuration

Some integrations allow configuration changes after connection. The modal shows **Save Changes** (**Save changes** on a multi-instance row) when there are unsaved edits. Saving updates the instance via the API. Read-only views show masked credentials.

***

### Using Multi-Instance Integrations

#### Understanding Multi-Instance Support

Some integrations support **multiple instances** (e.g., multiple Okta orgs, multiple MDM providers). The integration card indicates this with a badge showing the number of connected instances. Hover over the badge to see the name of each individual instance without truncation. Multi-instance integrations use a different modal that lists instances.

Multi-instance support is available for a wide range of integrations, including MDM providers such as Kandji, Jamf, JumpCloud, Intune, and Apple Business Manager (ABM), as well as Microsoft Teams, and others. Each instance is authenticated and managed independently, so device and application data from each source is tracked separately and never merged.

#### Adding Multiple Integration Instances

1. Open the integration by clicking its card.
2. Click **Create instance**. If no instance is connected yet, the form opens straight away. Slack works differently: once a workspace is connected, its card shows **Reauthorize**, which runs the Slack authorization again for that workspace. Accounts set up for more than one Slack workspace see **+ Add workspace** instead.
3. Enter an **Instance name**. It is required. Harmony often pre-fills a suggested name (for example, "Addigy Instance"), which you can edit. For OAuth integrations the suggestion appears only for the first instance.
4. **Form-based** - Fill in the configuration form and click **Connect**.
5. **OAuth** - Click **Connect** and complete the provider's sign-in. Some OAuth integrations support a limited number of instances; when all are used, you must delete an instance before adding another.
6. The new instance appears in the list.

![Multi-instance modal with Create instance and instance list](https://3514868215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXF7jyqNjJ1RPF9oUCnb%2Fuploads%2Fgit-blob-487bc58cce4e31ad3f5b8d6f51dc7990be063a51%2Fintegration-config-form.png?alt=media)

#### Managing Multiple Instances

The modal lists all instances with icon, name, domain (if present), and a "Connected" badge. For each instance:

* **View config** - Click to expand and see configuration. Fields are read-only, except those the integration lets you change after connecting.
* **Reconnect** - On many OAuth integrations, click the plug icon to authorize again at the provider. The instance keeps its settings.
* **Delete** - Click the trash icon. Confirm in the dialog. The instance is permanently removed.

#### Switching Between Instances

Instances are listed in the modal. Click an instance to expand its configuration section. When the integration has config fields, the expanded view shows them (read-only, except those the integration lets you change after connecting). Collapse by clicking again or selecting another instance. The active instance for workflows and features is determined by context (e.g., which instance is used for a specific desk or destination).

#### Connecting Multiple Microsoft Environments

You can connect multiple Microsoft Teams and Intune instances to Harmony within a single tenant. Each instance is authenticated independently using its own Entra ID and OAuth credentials, so you can manage all of your Microsoft environments from a single Harmony account without any overlap between instances.

#### Choosing the Right ServiceNow Connection Method

When connecting ServiceNow, you will see two options in the **IT Service Management** category: **ServiceNow (OAuth)** and **ServiceNow (Service Account)**. Both options are displayed side by side to make comparison straightforward. The OAuth option displays a **Recommended** badge when it is not yet connected, helping you quickly identify the preferred setup method. The badge is automatically hidden once a connection is established.

***

### Filtering and Browsing Integrations

#### Searching and Filtering

Type in the **Search** box to find an integration by name, or use the **Category** filter to show only the categories you pick. **Reset** clears both. Connected integrations carry a **Connected** badge on their card.

#### Integration Card Layout

The integrations settings page uses a compact card grid so you can see more integrations at a glance. Each card displays the vendor icon (with a consistent border for clear visual separation), the integration name, and connection status. When multiple instances are connected, a badge on the card shows the instance count - hover over it to see the individual instance names.

***

### Disconnecting Integrations

#### Disconnecting an Integration

**Single-instance**

1. Open the integration modal.
2. Click **Disconnect** in the footer.
3. Confirm in the dialog ("Are you sure you want to disconnect...").
4. The instance is deleted. The modal closes and a success toast appears.

**Multi-instance**

1. Open the integration modal.
2. Click the trash icon next to the instance you want to remove.
3. Confirm in the dialog ("Are you sure you want to delete this instance...").
4. The instance is deleted. The list updates; the modal stays open.

You can also remove an installed app from your workspace entirely from the integrations settings page. The uninstall process cleanly removes credentials and provider connections, and changes take effect immediately.

#### Understanding Disconnection Impact

* **Permanent** - The instance is deleted. There is no undo.
* **Dependent features** - Notification destinations, Knowledge Base sources, workflows, and other features that use this instance will stop working. Fix them by reconnecting or switching to another instance.
* **Asset and application data preserved** - Deleting an integration no longer removes the asset records or application data collected through it. All records - including any manual enrichments such as purchase info, assignee details, license information, or custom fields - remain visible and fully accessible in your dashboard after disconnection.
* **Software discovery** - When an integration is deleted, all associated software discovery data is cleanly removed to keep your workspace free of stale or orphaned records. When a new identity provider integration is connected, application discovery is automatically triggered so newly accessible applications are detected right away.

#### Reconnecting After Disconnection

To use the integration again:

1. Go to **Settings** → **Integrations**.
2. Open the integration by clicking its card (for a multi-instance integration that still has other instances, click **Create instance**).
3. Complete the setup flow (form or OAuth) as if connecting for the first time.
4. Reconfigure any dependent features (notifications, KB sources, etc.) to use the new instance.

***

### 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>Integration Sync &#x26; Credentials</strong></td><td>Bidirectional sync, credentials, and security</td><td><a href="https://docs.harmony.io/settings/configuring-integration-sync-and-credentials.md">Configuring Integration Sync and Credentials</a></td></tr><tr><td><strong>Understanding Integrations</strong></td><td>Integration categories, status, and OAuth</td><td><a href="https://docs.harmony.io/settings/understanding-integrations.md">Understanding Integrations</a></td></tr><tr><td><strong>Integrations Catalog</strong></td><td>Browse available integrations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/integrations/README.md">https://github.com/harmonyso/public-docs/tree/main/integrations/README.md</a></td></tr><tr><td><strong>Ticket Settings</strong></td><td>Set up notification channels</td><td><a href="https://docs.harmony.io/settings/managing-ticket-settings.md">Managing Ticket Settings</a></td></tr><tr><td><strong>Knowledge Base</strong></td><td>Add KB sources from integrations</td><td><a href="https://docs.harmony.io/settings/managing-knowledge-base.md">Managing Knowledge Base</a></td></tr></tbody></table>

***

## Where to find in the UI

1. Open **Settings** in the sidebar, at `/settings`.
2. Select **Integrations**, at `/settings/integrations`.
3. Find the integration you want and connect it, or open one already connected to manage its credentials and sync.

Integrations are grouped by category. Connected integrations show their status on the same page.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/settings/connecting-and-managing-integrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
