How to Use Pangolin Access Tokens with Helmarr

If you already use Pangolin for zero-trust access to your homelab, you can put Sonarr, Radarr, Tautulli, qBittorrent, Overseerr, Tdarr, and the rest of your media stack behind Pangolin and still connect them cleanly from Helmarr.

The key is to use Pangolin’s Access Token Usage flow for API clients. A normal Pangolin login page is great for humans in a browser, but Helmarr is a native app talking to service APIs. It should call the resource URL directly and send Pangolin access-token headers on every request.

flowchart TD
  A["Helmarr on iPhone, iPad, or Mac"] -->|"HTTPS + Pangolin token headers"| B["Pangolin public resource"]
  B --> C{"Pangolin auth"}
  C -->|"Link access token accepted"| D["Site / Newt connector"]
  C -->|"Browser user"| H["Pangolin login or Link redirect"]
  H --> D
  D --> E["Local service target"]
  E --> F["Sonarr / Radarr / Tautulli / qBittorrent / Tdarr"]
  F --> G["Service API key still required"]

What you will build

Helmarr will reach protected Pangolin public resources like these:

Each request has two layers of authentication:

• Pangolin access: Helmarr sends Pangolin access-token headers so the request can pass the Pangolin front door.
• Application access: Helmarr still sends the service’s normal API key or token after Pangolin lets the request through.

Important

Pangolin access tokens do not replace Sonarr, Radarr, Tautulli, qBittorrent, Overseerr, or Tdarr credentials. They only authenticate the Pangolin resource layer. Keep the app’s own API key or token in Helmarr too.

Prerequisites

You need:

• A working Pangolin Cloud or self-hosted Pangolin setup.
• A site that can reach your media services. For most remote-network setups, Pangolin recommends a Newt site.
• Public HTTPS resources for the services you want Helmarr to manage or monitor.
• Pangolin authentication enabled on those resources.
• API keys or tokens from the services themselves.
• Helmarr installed on iPhone, iPad, or Mac.

Step 1: Expose the service as a Pangolin resource

In Pangolin, a site represents the network where your services live. A resource represents the application, host, or network range you want users to access. Public HTTPS resources work like authenticated reverse-proxy entries: a hostname on the outside maps to a backend target on your private network.

Create a public HTTPS resource for each service Helmarr should reach. For Sonarr, the shape is usually:

Use the address from the Pangolin site or Newt connector’s point of view. If the connector runs in Docker, localhost:8989 means the connector container, not necessarily your Sonarr container. A Docker network hostname, host gateway address, or LAN IP is usually clearer.

Repeat the same pattern for Radarr, Tautulli, qBittorrent, Tdarr, and any other service you want in Helmarr.

Step 2: Keep Pangolin authentication enabled

Pangolin public resources can have an authentication layer in front of them. Human users can authenticate with Pangolin SSO, an external identity provider, email OTP, PIN/passcode, or other resource rules depending on your setup.

For Helmarr, avoid relying on an interactive login page. Helmarr needs a request-by-request credential it can send as an API client. That is where Pangolin Shareable Links and Access Tokens come in.

Warning

Do not expose a media service publicly without an authentication rule just because the app has its own API key. Sonarr, Radarr, and similar tools were usually designed for trusted networks. Keep Pangolin in front of them when they are reachable from the Internet.

Step 3: Create a Pangolin Link access token

Open the resource’s authentication flow in Pangolin and create a Link for the service.

When creating it:

1. Choose the exact resource, such as Sonarr.
2. Give it a clear title like Helmarr iPhone or Helmarr remote access.
3. Set an expiration that matches your security posture, or intentionally choose no expiration if you plan to revoke it manually later.
4. Copy the access-token details immediately.

Pangolin gives you two related things:

For Helmarr, use Access Token Usage, not the browser Link URL.

Step 4: Add Pangolin headers in Helmarr

Pangolin can accept the Link access token in the query string or in request headers. For Helmarr, headers are cleaner because the token does not have to live inside the service URL.

By default, Pangolin uses these headers:

P-Access-Token-Id: <token-id>
P-Access-Token: <access-token>

In Helmarr, add or edit the service:

The headers must be sent on every request. Helmarr custom headers are designed for this kind of proxy or access gateway credential.

Service-level vs network-level headers in Helmarr

Helmarr lets you put custom headers either on a single service or on a network.

For many Pangolin setups, each public resource has its own Link access token. In that case, add the two Pangolin headers directly on each Helmarr service.

If your setup deliberately uses the same Pangolin token/header pair for every service in a Helmarr network, add the headers once on the network instead. Then Sonarr, Radarr, Tautulli, Tdarr, and the other services in that network inherit them automatically.

A practical Helmarr network setup might look like this:

Step 5: Do not confuse Pangolin custom headers with Helmarr custom headers

Pangolin also has Custom Headers in the public resource Proxy tab. Those are static headers that Pangolin adds when it forwards the request to your upstream app.

For this guide:

• Helmarr custom headers are sent from Helmarr to Pangolin: P-Access-Token-Id and P-Access-Token.
• Pangolin proxy custom headers are sent from Pangolin to the backend service.
• Forwarded identity headers like Remote-Email only apply when Pangolin has user identity from an authentication method such as SSO. Link-based access does not carry per-user identity to the upstream app.

Step 6: Test the resource before adding every service

Before duplicating the setup across the whole stack, test one service.

From a terminal, run:

curl -I \
  -H "P-Access-Token-Id: <token-id>" \
  -H "P-Access-Token: <access-token>" \
  "https://sonarr.example.com/"

If Pangolin accepts the token, the response should come from the protected resource instead of a Pangolin login page.

Then test the service API itself. For Sonarr, that might be:

curl \
  -H "P-Access-Token-Id: <token-id>" \
  -H "P-Access-Token: <access-token>" \
  -H "X-Api-Key: <sonarr-api-key>" \
  "https://sonarr.example.com/api/v3/system/status"

Once curl works, copy the same URL, app API key, and Pangolin headers into Helmarr.

Troubleshooting

Helmarr gets a Pangolin login page

Helmarr is reaching the resource, but the request is not satisfying Pangolin auth. Check that you used the Access Token Usage values, not the browser Link URL, and confirm the header names are exact:

P-Access-Token-Id
P-Access-Token

Also confirm the headers are attached to the active Helmarr service or to the Helmarr network that service is using.

The Pangolin token works, but Sonarr or Radarr says unauthorized

That usually means the Pangolin layer accepted the request, but the app’s own API key is wrong or missing. Re-copy the Sonarr, Radarr, or Tautulli API key into Helmarr.

One service works and another does not

Pangolin Links are commonly tied to a specific resource. A token created for Sonarr may not authenticate requests to Radarr. Create a Link/access token for the failing resource, then add those headers on that Helmarr service.

The remote URL works at home but fails outside the LAN

Check DNS, the Pangolin resource hostname, the target, and whether the site connector is online. The resource URL in Helmarr should be the public resource URL, such as https://sonarr.example.com, not the private LAN URL when you are using the remote network.

You used Pangolin’s query parameter token

Pangolin also supports p_token=<token-id>.<access-token> in the URL. That can work for scripts, but headers are better for Helmarr because the token is not part of the URL string. Use the two custom headers when possible.

Security checklist

Before relying on the setup day to day:

• Use HTTPS public resource URLs in Helmarr.
• Keep a separate Pangolin Link/access token for each service or each trusted device when practical.
• Give access tokens reasonable expiration dates if you do not want permanent credentials.
• Revoke old Links when a device is lost, sold, replaced, or shared.
• Keep app API keys separate from Pangolin access tokens.
• Prefer Helmarr network-level headers only when the same token pair should apply to every service in that network.
• Keep Pangolin sites/connectors updated.
• Review Pangolin access logs if your edition supports them.

FAQ

Can I paste the Pangolin Link URL as the Helmarr service URL?

No. The Link URL is meant for browser validation and redirect. In Helmarr, use the actual resource URL, such as https://sonarr.example.com, and add the access-token headers separately.

Can one Pangolin token cover all my Helmarr services?

Only if your Pangolin setup makes that same token valid for every service you are adding. Since Links are created for a target resource, most setups use one token per service and set headers at the Helmarr service level.

Do I still need each app’s API key?

Yes. Pangolin authenticates access to the resource. Sonarr, Radarr, Tautulli, and the other apps still require their own API keys or credentials.

What about Pangolin private resources?

Private resources work more like a zero-trust VPN and require a Pangolin client connection. If your device has the Pangolin client connected and the private route is available, Helmarr may be able to use the internal service URL without access-token headers. For a simple native API-client setup across iPhone, iPad, and Mac, public HTTPS resources plus access-token headers are usually easier to reason about.

Are Pangolin forwarded identity headers useful for Helmarr?

Usually no. Forwarded headers are for upstream apps that understand user identity headers like Remote-Email. Helmarr is just trying to reach the service API, so the important headers are the Pangolin access-token headers plus the app’s own API key.

Next steps

Start with one service, preferably Sonarr or Radarr, and get the full chain working before adding the whole stack. Once the first service works, duplicate the pattern carefully: resource URL, Pangolin access-token headers, and the service’s own API key.

If you use Cloudflare instead of Pangolin, the same Helmarr idea applies with different gateway headers. See the companion guide: How to Set Up Cloudflare Zero Trust, Tunnel, and Service Tokens for Helmarr.

Sources and further reading

• Pangolin Docs
• Pangolin: Shareable Links and Access Tokens
• Pangolin: Public Resource Authentication
• Helmarr