> 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

{% 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.

**OAuth2**

* No form input before connecting. You authorize in the provider's popup.
* Ensure you have admin access if the provider requires it (e.g., Slack workspace admin).

**Descope OAuth2 (multi-instance)**

* The integration must have an available Descope app slot. If all slots are 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 and click **Connect**.
3. Complete the flow for your integration type:
   * **Form-based** - Fill in the configuration form (domain, credentials, etc.) and submit.
   * **OAuth2** - A popup opens; log in to the provider and approve permissions.
   * **Descope OAuth2** - Complete the Descope flow; if the integration has post-OAuth config fields, fill those and submit.

![Settings > Integrations with integration cards](/files/N60udCSjb6a1kShpdXTq)

#### Authorizing Integration Access

For OAuth integrations, the provider's authorization page opens 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 submit the form, a success toast appears and the modal closes.
* **OAuth2** - After you approve in the popup, the popup closes, a success toast appears, and the integration list refreshes.
* **Descope with post-OAuth config** - After OAuth, a configuration form may appear. Fill it in and save 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.

![Integration config modal with form fields and Save Changes](/files/DbOsuTabpKZXur8abblv)

#### 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 (`•••`) in read-only mode. Toggle visibility to view; changes require re-entering the value.
* **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., `cyera.kandji.com`) 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** 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 Slack workspaces, 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.
2. Click **Add instance** (or **Create instance**).
3. The **Instance name** field is automatically pre-filled with a suggested name based on the integration (for example, connecting Addigy pre-fills the field with "Addigy Instance"). You can edit this value before submitting, or clear it entirely - note that an empty name will be caught by validation.
4. **Form-based** - Fill in the configuration form.
5. **Descope** - Complete the OAuth flow. Each instance uses one Descope app ID; when all are used, you must delete an instance before adding another.
6. Submit. The new instance appears in the list.

![Multi-instance modal with Create instance and instance list](/files/mlj1r9ztEVFZudGLgCcn)

#### 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 (read-only when expanded).
* **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). 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 ITSM 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

#### Filtering by Connection Status

You can filter the integrations list by connection status to quickly find what you need. Use the status filter to show only connected, disconnected, or pending integrations, rather than scrolling through the full catalog. This is especially useful when managing a large number of integrations across your workspace.

#### 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 and click **Connect** (or **Add instance** for multi-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://github.com/harmonyso/public-docs/tree/main/guides/configuring-integration-sync-and-credentials/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/configuring-integration-sync-and-credentials/README.md</a></td></tr><tr><td><strong>Understanding Integrations</strong></td><td>Integration categories, status, 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>Integrations Catalog</strong></td><td>Browse available integrations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/integrations/overview/README.md">https://github.com/harmonyso/public-docs/tree/main/integrations/overview/README.md</a></td></tr><tr><td><strong>Ticket Settings</strong></td><td>Set up notification channels</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><tr><td><strong>Knowledge Base</strong></td><td>Add KB sources from integrations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-knowledge-base/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-knowledge-base/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/connecting-and-managing-integrations.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.