API Keys
A Houndarr API key is an inbound bearer credential for external
read-only clients. Homepage and other integrations use it to call
/api/v1/widget without borrowing a browser session or proxy-auth
header.
Credential types
| Credential | Direction | Storage | Used for |
|---|---|---|---|
| Instance API key | Houndarr to a Radarr, Sonarr, Lidarr, Readarr, or Whisparr instance | Fernet-encrypted in instances.encrypted_api_key | Searching and reading data from that instance. |
| Houndarr API key | External client to Houndarr | SHA-256 hash in widget_api_key | Calling Houndarr's external read-only widget endpoint. |
Both directions use an X-Api-Key header. The route decides which key
is expected.
Format
| Part | Value |
|---|---|
| Prefix | hndarr_ |
| Full display pattern | hndarr_<base64-urlsafe-32> |
| Random input | 32 random bytes generated by Houndarr |
| Transport | X-Api-Key request header |
The visible suffix is URL-safe Base64 text generated from 32 random bytes. Do not rely on a fixed visible character count.
Lifecycle
| Step | Behavior |
|---|---|
| Generate | Settings > Admin > API key creates a new key, stores only its hash, and shows the plaintext once. |
| Store externally | Copy the plaintext key into Homepage or another client configuration. Houndarr cannot show it again. |
| Use | Send X-Api-Key: hndarr_... on GET /api/v1/widget. |
| Regenerate | Replaces the single stored hash, clears last_used_at, and invalidates the old key on the next request. |
| Revoke | Deletes the stored row. /api/v1/widget returns 401 until a new key is generated. |
One Houndarr installation has at most one active Houndarr API key. Regeneration is rotation, not creation of a second named key.
Stored metadata
| Field | Where it appears | Behavior |
|---|---|---|
created_at | Settings > Admin > API key | Timestamp for the current active key. Regeneration resets it. |
last_used_at | Settings > Admin > API key | Updated after a successful /api/v1/widget request. Shows Never before first use. |
hash | SQLite widget_api_key table | SHA-256 digest of the plaintext key. The plaintext is never decrypted because it is not stored. |
Authentication behavior
| Request | Result |
|---|---|
Valid X-Api-Key on /api/v1/widget | The request succeeds in built-in auth and proxy auth modes. |
| Missing, invalid, regenerated, or revoked key | Houndarr returns 401 with WWW-Authenticate: ApiKey. |
| Repeated failed key attempts | Houndarr returns 429 with Retry-After: 60 after the failed-attempt window is exhausted. |
Session cookie or proxy-auth header without X-Api-Key | /api/v1/widget still returns 401. |
The Houndarr API key authorizes only /api/v1/widget. It does not
authorize Settings, logs, instance configuration, search actions, or any
write endpoint.
Handling rules
- Treat the Houndarr API key as a bearer secret.
- Store it in the external client's secret or config mechanism.
- Do not put it in query strings, browser bookmarks, screenshots, or logs.
- Regenerate it if it was pasted into the wrong place.
- Revoke it when the external client no longer needs widget access.
For the endpoint contract, see Widget API. For a Homepage setup recipe, see Homepage Integration.