---
title: "Homarr Integrations — Third-Party App Connections"
aliases: [homarr-integrations, homarr-third-party]
tags: [homarr, homelab, integrations, self-hosted]
sources: [raw/Homarr documentation 4.md]
created: 2026-04-19
updated: 2026-04-19
---

## What Are Integrations

Integrations are authenticated connections to supported third-party applications (SABnzbd, *arr stack, etc.). They power widgets that pull live data or perform actions — distinct from [[wiki/homelab/homarr-apps|Apps]], which are simple URL bookmarks.

## Creating an Integration

1. Pick the app from the dropdown (top-right of the integrations page)
2. Fill required fields:

| Field | Rules |
|-------|-------|
| **Name** | Any string, min 1 character |
| **URL** | Base URL only — no trailing paths (`/settings`, `/api`, etc.) |
| **Secrets** | App-specific tokens/passwords; encrypted at rest, never sent to client |

3. Optionally link an [[wiki/homelab/homarr-apps|App]] — sets the click-through URL and is reused by integration widgets
4. Click **Test & Create** — creation is blocked until the test passes

> Secrets are stored with symmetric encryption. All requests to integrations are made server-side (from the Homarr host), never from the browser.

## Permission Levels

Three tiers per integration, assignable to users or groups:

| Permission | What It Allows |
|------------|---------------|
| **Select** | Use the integration in widgets; view its data on boards |
| **Interact** | Perform actions (e.g. pause a download) |
| **Full Control** | Edit URL, secrets, and all integration properties |

See [[wiki/homelab/homarr-boards|Homarr Boards]] for how board-level access control interacts with integration permissions.

## Troubleshooting Connection Failures

Work through this in order — most issues are caught early:

1. **URL** — base URL only, no paths appended
2. **Secrets** — correct value and sufficient permissions
3. **HTTPS / certs** — if using self-signed, add it via [[wiki/homelab/homarr-certificates|Homarr Certificates]]
4. **Homarr docs** — re-read the integration-specific page; skipped steps are the #1 cause
5. **Homarr logs** — upstream API breaking changes surface here
6. **Host connectivity** — `ping` + `curl`/`wget` from the host (not inside the container)
7. **Container connectivity** — same commands from inside the container/pod shell
8. **Reverse proxy logs** — check for auth failures or blocked requests
9. **VPN / tunnel logs** — security events that silently drop traffic
10. **Router security events**
11. **VLAN + firewall rules**
12. **DNS** — verify hostname resolution on both host and containers
13. **Network throughput** — `iperf3` for stability issues
14. **OS syslog / drivers**
15. **Destination app logs** (e.g. SABnzbd's own log)
16. **Last resort** — disable CSRF/tamper protection temporarily (re-enable if it doesn't help)

If none resolve the issue → Discord or GitHub support.

### Certificate Issues

Self-signed certs fail silently. Fix:
- Use [[wiki/homelab/homarr-certificates|Homarr Certificates]] to upload the cert, **or**
- Click the auto-add button that appears on connection failure
- Verify the cert fingerprint before trusting (MITM prevention)

## Key Takeaways

- Integrations ≠ Apps — integrations are authenticated data/action connections; apps are URL shortcuts
- URL must be the base URL with no path suffix — this is the most common misconfiguration
- Secrets are server-side only; never exposed to the browser
- Creation is gated behind a live connection test — no broken integrations get saved
- Three permission levels (Select / Interact / Full Control) are assignable per user or group
- Self-signed cert errors → [[wiki/homelab/homarr-certificates|Homarr Certificates]] is the fix
- Troubleshoot network issues from the outside in: host → container → proxy → firewall → DNS

## Sources

- `raw/Homarr documentation 4.md` — https://homarr.dev/docs/management/integrations/ (v1.59.2)
