---
title: "Homarr documentation"
source: "https://homarr.dev/docs/management/integrations/"
author:
published:
created: 2026-04-19
description: "Integrations are connections to supported third party applications."
tags:
  - "clippings"
---
Version: 1.59.2

Integrations are connections to supported third party applications. This page will describe the process of managing integrations but the process may vary depending on your specific integration. Check [the available integrations](https://homarr.dev/docs/category/integrations) for further information.

## Create an integration

To create an integration, you can choose the supported application from the dropdown at the top right:

![[b403f6e2ad41cd95c9ef0ab2c9037757_MD5.png]]

Next, you'll need to fill out the required fields to configure the integration:

![[28719542ceeb925d0a749a6fbd41b81a_MD5.png]]

### Name

Must be at least 1 character long, can be chosen freely.

### Url

This must be the base URL of the application where Homarr should connect to. A few examples for this field include:

- [http://sabnzbd.example.com](http://sabnzbd.example.com/)
- [https://example.com/sabnzbd](https://example.com/sabnzbd)

You must not append any path after the base URL. Some examples for incorrect usage:

- [http://sabnzbd.example.com/settings](http://sabnzbd.example.com/settings)
- [https://example.com/sabnzbd/settings](https://example.com/sabnzbd/settings)

### Secrets

An integration may or may not require secrets to function. To process to obtain them is usually [documented in the integration pages](https://homarr.dev/docs/category/integrations). Secrets are encrypted using a symmetric encryption and stored in the database. To improve security, they will never be passed to the client and requests to the integrations are performed from the host where Homarr is running on.

### Linking applications

During the creation of an integration you can choose to add / link an application to the integration. If you want to add one, you can simply specify the app url which will be used for opening the application from Homarr. The linked application will also be used for any links the integration widget contains. If you already have an application created, you can also link it to the integration by selecting it from the dropdown. On the edit page you can always change or remove the linked application.

### Testing and saving integration

It is not allowed to create an integration without passing the test. This is to ensure that you minimize the amount of broken applications on your Homarr instance. The test and create button will perform a network request to the application and authenticate if required.

## Managing permissions

On the edit page of an integration, you can manage which users / groups can

- **Select the integration in items:** Allows users to select the integration and showing data on their board.
- **Interact with the integration:** Allows users to perform actions on the integration, such as pausing a download.
- **Full control over the integration:** Allows users to modify the integration properties, including the URL and secrets.

![[2af628de56b4534249e652d8e4334fdd_MD5.png]]

## Troubleshooting connection

The connection to your integrations can fail due to many factors. Most of the time it should show you the reason why it failed. If it doesn't, you can follow these steps to troubleshoot the issue:

1. Check whether you are using the correct URL and secrets.
	- The URL must be the base URL of the application, **without any paths**.
		- The secrets must be correct and have the correct permissions.
2. If you use https to connect to the application, check the chapter below about [certificate issues](#certificate-issues).
3. Check whether you followed the Homarr documentation and didn't skip any steps. This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems.
4. Check Homarr's logs for more information. As we have no control over breaking changes in upstream APIs and third party software, they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported and fixed within the source code of Homarr.
5. Check whether the host can reach the destination hostname / IP using `ping` and `curl` or `wget` afterward. Execute this command on the host machine, not inside containers, to check whether it can connect or not.
6. Check whether the container / pod can reach the destination hostname / IP. Execute the same commands in the shell inside the container / pod.
7. Check your reverse proxy / authentication proxy logs for failures / hints
8. Check your security log of tunnels and VPNs
9. Check your router for security events
10. Check your VLAN configuration and firewall rules
11. Check your DNS settings for the host machine and the containers / pods and whether they can resolve the hostnames
12. Check throughput and stability of your network connection using `iperf3`
13. Check syslog / drivers of your OS for hints
14. Check logs of your destination applications (eg. SABnzbd)
15. Attempt to disable CSRF / tamper protections when absolutely no other workaround available -> this comes with some security implications - be careful! Re-enable if this didn't fix the issue.

If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub.

### Certificate issues

If you are using a self-signed certificate you'll need to add it to the [trusted certificates](https://homarr.dev/docs/management/certificates) in Homarr. Most of the time you should also get a button to add the certificate automatically when you try to connect to the integration. Please check that the certificate is the one you are expecting to prevent Man in the Middle attacks. For some integrations, you can find a guide on how to retrieve the certificate [here](https://homarr.dev/docs/management/certificates/#obtaining-certificates).