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	ZIP	Bundles config.json (with every secret masked as ***configured***), your language profiles, and glossary into one archive. Credentials never leave Sublarr in the clear.
Import	ZIP / CSV	Reads a Sublarr ZIP export (config + profiles + glossary) or a CSV of keys. Any value still masked with *** is skipped, so re-importing your own export never wipes a live key.
Bulk paste	CSV	Paste rows of service,key_name,key_value to load many keys at once during first-time setup.

Note

The export never contains your credentials in plaintext — it only carries masked placeholders. The real keys stay in Sublarr’s database, encrypted at rest with Fernet (AES-128) under a master key held in <config>/.encryption_key, outside the database. To move keys to a new install, copy that key file alongside your database — or use Settings → System → Backup, which bundles both — then re-enter or CSV-import anything you didn’t migrate. See Settings — System for the full mechanism.

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.