API Keys

The API Keys page is a unified credential vault. Every key Sublarr sends out — to OpenSubtitles, Jimaku, SubDL, Sonarr, Radarr, Plex, Jellyfin, Emby, TMDB, TVDB, and the LLM backends — is listed here, with test buttons, rotation flags, and import/export. It’s the audit trail you reach for when something stops authenticating.

Key types

Type	Used by	Where it’s also editable
Provider key	OpenSubtitles, Jimaku, SubDL, Whisper, Subgen, others	Settings → Providers
Arr key	Sonarr, Radarr	Settings → Connections
Media server token	Plex, Jellyfin, Emby	Settings → Connections
Metadata key	TMDB, TVDB, AniDB	Settings → Connections → Metadata
LLM key	Anthropic, OpenAI, Gemini, DeepSeek, Mistral, DeepL, Azure	Settings → Translation → Backends
Inbound API key	The X-Api-Key callers must present to talk to Sublarr	Settings → System → Security

Editing a key on its origin page (e.g. on Settings → Providers) and editing it here change the same database row.

Multi-key pools

Some providers support multiple keys rotated automatically when one hits a daily quota. Each key carries:

Field	Effect
Label	Human-readable identifier (“Free tier” / “Paid”).
Key	The credential itself. Masked in the UI; shown when editing.
Tier	free / paid — affects rotation order.
Username / Password	Optional — required by some providers.
Enabled	Toggle without deleting. Disabled keys aren’t tried.

Sublarr cycles through enabled keys in paid → free order, retrying on 429 and rotating to the next key when the current one is rate-limited. The Test button next to each key dry-runs the provider’s auth endpoint and reports the result without touching real subtitle traffic.

Tip

Add at least two keys for OpenSubtitles, Jimaku, and SubDL if you have them — providers occasionally throttle aggressively, and a paid + free pair gives you graceful fallback without writing a single line of config.

Test all

The page header has a Test all button that round-trips every enabled key in parallel, reporting status as OK, failed, or rate-limited per row. Use it after a config import or when subtitle searches start failing en masse — it tells you in one view which credentials are the problem.

Import / Export

Below the key list:

Button	Format	What it does
Export	YAML	Dumps every key (masked) plus the credential structure. The actual key strings are exported separately to an encrypted blob if you tick Include secrets.
Import	YAML	Reads a previously exported file. Conflicts (existing key for the same provider) prompt for “overwrite / keep / merge”.
Bulk paste	CSV	Paste a CSV (provider,label,key,tier,enabled) for first-time setup of many keys at once.

Caution

The “Include secrets” export contains live credentials. Treat the resulting file like a password manager dump — encrypt at rest, never commit to git, and rotate keys if it ever leaks.

Inbound API key

The last section is the API key Sublarr expects on incoming requests (the X-Api-Key header):

Field	Effect
Current key	The active value. Click reveal to show.
Generate	Creates a new random key (32 hex chars). The old key remains valid until Save — preventing self-lockout.
Disable auth	Sets the key to empty. Sublarr accepts unauthenticated requests.

Danger

Disabling inbound auth removes the only barrier between your Sublarr instance and the network. Only do this on a fully trusted LAN, never with SUBLARR_CORS_ORIGINS=* set, and never behind a reverse proxy that doesn’t enforce its own auth.

Activity audit

Every key change writes to Activity → History with the operator user, the field, and a redacted before/after. Use the History filter on subsystem = api_keys to retrieve the full audit trail for compliance or post-incident review.