> 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/understanding-integrations.md).

# Understanding Integrations

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

### Understanding Harmony Integrations

#### What are Integrations?

Integrations connect third-party systems to Harmony. They enable Harmony to sync data, trigger actions, and work with tools like Slack, Okta, Jamf, Confluence, and many others. Each integration brings capabilities such as user sync, ticket creation, device management, knowledge base content, or notifications.

#### Benefits of Integrations

* **Single entry point** - Support and operations from one place instead of switching between tools
* **Unified workflows** - Automate across systems (e.g., create tickets from Slack, provision access via Okta)
* **Data sync** - Keep employees, assets, and applications up to date across your stack
* **AI and automation** - AI agents and workflows use integration data to resolve issues and route work

#### Viewing Available Integrations

1. Go to **Settings** → **Integrations**.
2. The page lists all available integrations, grouped by category.
3. Use **Search** to find a specific integration by name.
4. Use the **Category** filter to narrow by type (Collaboration, Identity Provider, MDM, etc.).
5. The URL supports `?integration-id=...` for deep linking to a specific integration.

Each integration card shows the name, description, category, and connection status.

![Integrations list with category filter and cards](/files/q57q0W3SoVucD7eznRNZ)

***

### Understanding Integration Categories

Integrations are organized into categories:

| Category                | Description                      | Examples                                              |
| ----------------------- | -------------------------------- | ----------------------------------------------------- |
| **Collaboration**       | Team communication tools         | Slack, Microsoft Teams                                |
| **Identity Provider**   | Identity and access management   | Okta, Microsoft Entra, Google Workspace, JumpCloud    |
| **MDM**                 | Mobile device management         | Jamf, Kandji, Intune, JumpCloud MDM                   |
| **EDR**                 | Endpoint detection and response  | CrowdStrike, SentinelOne                              |
| **Ticketing**           | Issue tracking and ticketing     | Zendesk, Freshservice                                 |
| **ITSM**                | IT Service Management            | Atlassian, ManageEngine, SolarWinds                   |
| **HRIS**                | Human Resources systems          | BambooHR, HiBob, Workday, Ceridian, Sage HR, UKG Pro  |
| **Knowledge Base**      | Knowledge base platforms         | Confluence, Notion, Freshservice, SharePoint, Simpplr |
| **Software Management** | Software inventory and licensing | Torii                                                 |
| **Asset Management**    | IT asset management              | Workwize                                              |
| **SaaS Applications**   | General SaaS apps                | GitHub, Monday, Zoom                                  |
| **Design**              | Design and creative tools        | -                                                     |
| **AI**                  | AI and ML platforms              | -                                                     |

***

### Understanding Integration Status

#### Connected Status

When an integration is connected, the card shows a **Connected** badge (green). For multi-instance integrations (e.g., multiple Slack workspaces), the count of instances is shown. Hover for a tooltip listing the instances.

![Integration card with Connected badge](/files/RhdhBUUXBOLFRXAtXRYb)

#### Disconnected Status

When no instances exist, the integration is disconnected. There is no explicit "Disconnected" badge; the absence of "Connected" indicates it is not set up. Click **Connect** to start the setup flow.

#### Deprecated Status

Some integrations may be marked **Deprecated**. Deprecated integrations that are already connected can continue to work, but new configuration may be restricted. Plan to migrate to a supported alternative when available.

#### Error and Syncing Status

The UI does not currently display an "Error" or "Syncing" status on integration cards. Connection health is managed by the backend. If an integration stops working, disconnect and reconnect it, or check the integration's documentation for troubleshooting.

***

### Understanding OAuth Authentication

Many integrations use OAuth for secure, delegated access. Harmony supports different auth types:

#### What is OAuth?

OAuth lets Harmony access a third-party service on your behalf without storing your password. You authorize the connection once; Harmony receives tokens to make API calls. Tokens can be refreshed automatically.

#### OAuth Flow Overview

![Integration card with Connect button](/files/ftyeU9E5Q8Zeh7sz3wtb)

**Standard OAuth2 flow:**

1. Click **Connect** on the integration card.
2. Harmony requests an install URL from the backend.
3. A popup window (600×700) opens the provider's authorization page.
4. Log in to the provider (if needed) and approve the requested permissions.
5. The provider redirects back; the popup closes.
6. Harmony detects the success and refreshes the integration list. A toast confirms the connection.

**Descope-hosted OAuth2:**

Some integrations use a Descope-managed flow. The process is similar: click Connect, complete the auth in a redirect or popup, and return to Settings. The redirect URL includes `integration-id` for context.

#### Authorization Process

When you authorize an integration:

* The provider shows the permissions (scopes) Harmony is requesting.
* Review and approve them. Without approval, the connection cannot be completed.
* Some integrations may require admin approval in the provider (e.g., Slack workspace admin).

#### Token Management

Tokens are stored and managed by Harmony's backend (or Descope for Descope-based integrations). The UI does not expose tokens. Token refresh happens automatically. If a token expires and cannot be refreshed (e.g., revoked in the provider), disconnect and reconnect the integration.

#### Understanding OAuth Scopes

**Scopes** define what Harmony can do in the connected system (e.g., read users, send messages, list channels). Each integration has predefined scopes. The provider's authorization screen lists them. Harmony requests only the scopes needed for that integration's features.

#### Credentials-Based Integrations

Some integrations use **credentials** (e.g., API keys) instead of OAuth. For these, you enter the credentials in a configuration form after clicking Connect. Credentials are stored securely by the backend.

***

### 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>Connecting Integrations</strong></td><td>Connect, configure, and disconnect integrations</td><td><a href="https://github.com/harmonyso/public-docs/blob/main/guides/connecting-and-managing-integrations/README.md">https://github.com/harmonyso/public-docs/blob/main/guides/connecting-and-managing-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/blob/main/integrations/overview/README.md">https://github.com/harmonyso/public-docs/blob/main/integrations/overview/README.md</a></td></tr><tr><td><strong>User Management</strong></td><td>Notification destinations use connected integrations</td><td><a href="https://github.com/harmonyso/public-docs/blob/main/guides/managing-user-management/README.md">https://github.com/harmonyso/public-docs/blob/main/guides/managing-user-management/README.md</a></td></tr><tr><td><strong>Knowledge Base</strong></td><td>Connect KB sources (Confluence, Notion, etc.)</td><td><a href="https://github.com/harmonyso/public-docs/blob/main/guides/managing-knowledge-base/README.md">https://github.com/harmonyso/public-docs/blob/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/understanding-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.