Core concepts
Services, apps, and proxies
Section titled “Services, apps, and proxies”| Concept | Represents | Example |
|---|---|---|
| Service | An upstream instance with its base URL and original API key | Your Radarr server |
| App | An integration, with a name, URL slug, optional template, and active state | Homepage |
| Proxy | The connection between an app and a service, with its own key and permissions | Homepage → Radarr |
| Template | A starting allowlist grouped by service type | Homepage’s Radarr and Sonarr endpoints |
One app can connect to several services through separate proxies. Several apps can also connect to the same service. Each app/service pair has one proxy.
The app’s slug creates a shared URL prefix, such as /proxy/homepage. The proxy key selects which of that app’s services receives a request. A Radarr proxy and a Sonarr proxy can therefore share the same URL while using different keys.
Three kinds of credentials
Section titled “Three kinds of credentials”| Credential | Where it is used |
|---|---|
| Administrator username and password | Sign in to the Middlewarr dashboard; administration then uses a session cookie |
| Service API key | Stored with the service and supplied by Middlewarr to the upstream instance |
| Proxy API key | Supplied by the integration to authenticate a particular proxy |
The bootstrap token is a separate, temporary credential used to claim a new installation. Neither a service key nor a proxy key signs you in as administrator.
How a request is handled
Section titled “How a request is handled”- The request arrives at
/proxy/{appSlug}/.... - Middlewarr finds the active app and uses the supplied proxy key to select a configured, active proxy.
- It matches the remaining URL path and HTTP method against that proxy’s effective allowlist.
- If allowed, it forwards the request to the service with the service’s API key and returns the upstream response.
An unrecognized credential or unavailable app/proxy is rejected with 401. An authenticated request outside the allowlist is rejected with 403.
Where permissions come from
Section titled “Where permissions come from”A proxy inherits the app template’s endpoints for its service type. Local endpoint overrides replace the method list for individual paths. Paths with no grant are blocked.
Choosing a template can grant access immediately. A proxy with no template and no local grants starts with no allowed endpoints.
Permissions apply to paths and HTTP methods. Granting a parameterized route such as /api/v3/movie/{id} applies to every matching movie ID; it does not restrict access to a particular movie. Read Endpoint permissions before broadening access.
Pausing access
Section titled “Pausing access”Pause an app to stop access through all of its proxies. Use Stop traffic on one proxy to stop only that app/service connection. Resuming the app does not turn on proxies you stopped individually.
Stopping traffic preserves configuration. Deleting an app or service also removes its associated proxies, so use the pause controls for temporary changes.