Skip to main content

Credentials & Security

Credentials allow Yattee Server to access content that requires authentication -- age-restricted videos, premium content, region-locked material, and password-protected streams. Currently, Yattee Server supports authentication via cookie files in Netscape format.

How Credentials Work​

When Yattee Server extracts video information or streams content through yt-dlp, it passes any configured credentials for the relevant site as command-line flags. This allows yt-dlp to authenticate on your behalf without exposing credentials to clients.

Add Site with Credentials

The cookies_file credential type maps to the yt-dlp --cookies flag. It accepts cookie file contents in Netscape format, which is the standard format used by browser cookie-export extensions.

Recommended for YouTube

The most reliable method for YouTube authentication is exporting cookies from your browser using an extension like "Get cookies.txt LOCALLY", then pasting the contents into the credential value field.

Setting Up Credentials​

YouTube with Cookies​

  1. Install a cookie export extension in your browser (e.g., "Get cookies.txt LOCALLY" for Chrome/Firefox).
  2. Log into YouTube in your browser.
  3. Export cookies for youtube.com in Netscape format.
  4. In the Yattee Server admin panel, navigate to the YouTube site configuration.
  5. Add a new credential of type cookies_file.
  6. Paste the entire cookie file contents into the value field.
  7. Save and use the Test button to verify the credentials work.

Testing Credentials​

Each site in the admin panel has a Test button that attempts to extract a video URL using the configured credentials. This is the quickest way to verify that your credentials are working correctly. If the test fails, check the server logs for detailed error messages from yt-dlp.

YouTube rotates account cookies over time. A rotated cookie jar doesn't fail loudly: YouTube treats it as logged out and extraction quietly drops to 360p-only formats. Yattee Server watches for this and marks such cookies as stale.

The server checks YouTube cookies:

  • when they are uploaded, at startup, and then every hour, by asking youtube.com whether the jar is still signed in
  • when yt-dlp reports that the account cookies are no longer valid
  • when an extraction with cookies fails but an anonymous retry succeeds (three times within 10 minutes)

Stale cookies are skipped, so the server falls back to anonymous access instead of serving degraded results. If a later check finds the session signed in again, the cookies are used again automatically.

In the admin panel:

  • The Sites list shows a Cookies expired badge on sites with stale cookies.
  • Each credential shows Stale since with the date it was marked, or Validated with the last successful check. Hover it to see the last error.
  • The Validate button on a site re-checks its cookies right away. It is shown only for sites the check supports (currently YouTube).
Fixing expired cookies

Export a fresh cookie file from your browser (see YouTube with Cookies) and replace the stale credential. To make cookies last longer, export them from a private browser window that you close right after exporting, so the browser doesn't rotate them.

Encryption​

Sensitive credential values are automatically encrypted at rest using Fernet symmetric encryption (AES-128-CBC with HMAC-SHA256 authentication).

The cookies_file credential type is encrypted before being stored in the database.

Encryption Key​

The encryption key is auto-generated on first server startup and stored at:

{DATA_DIR}/.encryption_key

The key file is created with restricted permissions (0600 -- owner read/write only).

You can also provide your own encryption key via the CREDENTIALS_ENCRYPTION_KEY environment variable. If set, this takes precedence over the file.

Encryption key loss is unrecoverable

If the .encryption_key file is deleted or corrupted and you have not backed it up or set CREDENTIALS_ENCRYPTION_KEY, all encrypted credentials become permanently unrecoverable. You will need to re-enter every credential.

Always include the DATA_DIR directory in your backup strategy.

API Security​

Credential values are never exposed in API responses. When querying credentials through the API, the server only returns:

{
  "type": "cookies_file",
  "has_value": true
}

The actual credential content is never transmitted back to any client.

When yt-dlp needs to use a cookies_file credential during extraction:

  1. The decrypted cookie contents are written to a temporary file with 0600 permissions.
  2. The temp file path is passed to yt-dlp via the --cookies flag.
  3. After yt-dlp completes (success or failure), the temp file is immediately deleted.

This ensures cookie data exists on disk only for the duration of the extraction.