API Keys#

MetaTana can use local provider keys for direct metadata, artwork, subtitle, AI, and sync workflows. Pro hosted features can also use MetaTana-managed hosted provider access where enabled.

Provider keys are in Settings › Providers › Your keys, with a provider account link, a health check, and Save for each one. The local MetaTana API key is API key under Settings › Maintenance › Advanced.

Guided TMDb Key Setup#

MetaTana walks you through getting a free personal TMDb key and checks it with TMDb before saving it. No MetaTana Pro plan is needed for this.

You can open the guided steps from:

• First-run setup, before the first scan: Add a TMDb key now so posters appear right away → Add TMDb key. Later skips it. Pro accounts don't see this step.
• Library, when titles have no provider metadata yet: the N titles need posters and details card → Add a free TMDb key (2 minutes). The card can be collapsed but stays until a key or Pro is ready. Its other button, Sign in for Pro, is for hosted metadata.
• Home: the Improve matches line, with the unscraped count, Add TMDb key, See Pro plans, and Not now.
• Settings › Providers: More → Key setup → Add TMDb key step by step.

The Add a free TMDb key dialog has four steps:

1. Create a free TMDb accountOpen TMDb sign-up opens TMDb in your browser (the system browser on desktop). Confirm the email TMDb sends, then sign in. Skip this if you already have an account.
2. Request an API keyOpen TMDb API settings opens TMDb's API page. Choose to request a key, pick Developer, accept the terms, and fill in the short form about your personal use.
3. Copy one valueCopy the API Key or the API Read Access Token. Either one works.
4. Paste it herePaste into the field. MetaTana checks the value with TMDb as soon as you paste it. You can also type it and select Check and save. When TMDb accepts it, the dialog shows TMDb accepted the key. Saved. and closes.

A value TMDb rejects is never saved, so a wrong paste can't replace a key that already works. The key is stored in MetaTana's local app data and is only sent to TMDb.

After a key is saved from Library, MetaTana starts Scrape all unscraped on its own. After a key is saved from Settings › Providers, that scrape starts the next time you open Library. After a key is saved in first-run setup, the first scan uses it for posters and details.

If the check fails, the dialog says why:

Missing Or Rejected Keys During A Scrape#

A scrape that fails because of a key says so instead of "No match found":

Other providers use their own name in the same messages.

Metadata Keys#

Common local metadata keys:

AI Keys#

AI features need an active Pro plan, whether they use your own AI provider key or hosted AI Vision. A saved Anthropic or OpenRouter key does not unlock AI on Free, and the key test is Pro-only too. With Pro, AI Insights uses your own key; hosted AI Vision uses the MetaTana account and credit system instead of exposing hosted provider keys to the local client.

Sync Keys#

Trakt credentials are used for app-side watched-state sync (history, both ways). Ratings are not synced. Trakt is not routed through hosted Skyhook metadata.

Subtitle Keys#

Subtitle providers (OpenSubtitles and SubDL, Pro) are set up in Settings › Providers › Subtitles for subtitle search and fetches. If no subtitle provider is set up, subtitle actions say so instead of running a search.

Where Saved Keys Are Stored#

Where a saved key lives depends on how you run MetaTana. Settings › Providers says which case applies to your install.

The same storage covers your MetaTana local API key, the background Pro session, your Trakt sign-in, media server sign-ins (Plex, Jellyfin, Emby, and Kodi tokens, API keys, and passwords), and saved webhooks (their addresses carry the receiving service's token).

A keychain-encrypted key opens only on the computer that saved it. If you move the app data folder to another computer, or your system keychain is reset, Settings › Providers lists Saved keys can't be opened on this computer, and the key's row shows Can’t be opened here. Paste the key again to keep using it. MetaTana never sends an encrypted value it can't open:

• Your local API key is replaced with a new one automatically, so the app opens as usual. API key under Settings › Maintenance › Advanced says New key: data came from another computer. Scripts and MCP clients that used the old key need the new one.
• Trakt client ID and secret: the Trakt card on Sync shows Trakt keys can’t be opened here. Paste them again in Settings › Providers › Trakt client keys, then reconnect Trakt.
• Trakt shows Reconnect needed. Reconnect to sign in again.
• Media servers: the server card on Sync asks for the token, API key, or password again. Until you enter it, MetaTana does not contact that server.
• Webhooks shows Saved webhooks can't be opened on this computer. Add them again. Nothing is sent until you do.

If your system keychain is locked or refuses MetaTana, the desktop app shows MetaTana can't open your system keychain. Unlock it, then reopen MetaTana. and changes nothing until it can.

If keys stay locked, Clear saved keys under Settings › Providers (or on the keychain screen) removes only the keys this computer can't open and lists them to enter again. There is no Undo. If the keychain was reset, MetaTana restarts and starts a new keychain store.

Settings backup files (JSON) never include saved keys or the Trakt sign-in, so after restoring one, enter your keys again and reconnect Trakt. They do include your webhooks, with their full addresses, so keep backup files private.

Public Safety#

When documenting or sharing configuration:

• show key names only
• redact values
• do not paste hosted session tokens
• do not paste webhook secrets
• do not include one-time email codes
• do not include billing or provider dashboard secrets