> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/providers/authentication/auth-media-servers/auth-plex.md).

# Auth: Plex

Plex is a media server for your personal library. CrossWatch connects using a Plex account token (OAuth-style). No password is stored.

{% tabs %}
{% tab title="End users" %}

### What it supports

* Watchlist
* Ratings
* History
* Progress

{% hint style="info" %}
CrossWatch stores your **account token**, not your Plex password.
{% endhint %}

<figure><img src="/files/tONqnlBE1inscJWLrNwC" alt=""><figcaption></figcaption></figure>

### Connect Plex

1. Click **Connect Plex**.
2. A new tab opens and asks for a PIN.
3. Copy the PIN from **Link code** in CrossWatch. Paste it into the Plex page.
4. After Plex accepts the PIN, close the Plex tab.
5. Back in CrossWatch, open **Settings** for Plex.
6. Verify these values are filled:
   * **Server ID**
   * **Username**
   * **Account ID**
7. Click **Save**.

### Plex users: owner, managed users, and friends

Plex can return several user types in the user list:

* **Owner** — the Plex account that authenticated CrossWatch
* **Managed user** — a user inside the owner’s Plex Home
* **Friend or shared user** — a separate Plex account with access to one or more shared libraries

A friend or shared account is **not** the same as a Plex Home managed user.

#### What the token can access

CrossWatch stores the token from the Plex account that completed the sign-in flow.

Selecting a friend or shared user does **not** give that token access to the friend’s personal Plex account data.

That can affect:

* Watchlist
* Ratings
* History
* Progress

These operations can fail, return no data, or be rejected by Plex.

{% hint style="warning" %}
Do not select a Plex friend while using the server owner’s Plex profile.

The owner’s token usually cannot read or modify that friend’s personal Plex data.
{% endhint %}

When requested user scope cannot be applied, CrossWatch stops the operation.

It does **not** silently fall back to the token owner’s watchlist, ratings, history, or progress.

#### Recommended setup

For a friend or shared account, create a separate Plex profile and authenticate it with that user’s own Plex account.

1. Open **Settings → Authentication → Plex**.
2. Create a new Plex profile.
3. Start the Plex connection flow for that profile.
4. Complete Plex sign-in while logged in as the friend’s Plex account.
5. Configure the Plex server URL and load the libraries available to that account.
6. Save the Plex profile.
7. Use that Plex profile in sync pairs, Watcher routes, and Playback Progress.

The friend’s Plex account must already have access to the Plex server and the required libraries.

If that user also syncs to a personal tracker account, create a separate tracker profile for that user too.

Related: [Profiles](/crosswatch/profiles.md).

#### Plex Home managed users

Plex Home managed users work differently from friends.

CrossWatch can try to switch the authenticated Plex Home account into the selected managed user.

If the managed user is protected by a Plex Home PIN, configure the correct PIN too.

Use the server owner’s Plex profile for Plex Home managed users.

Use a separately authenticated Plex profile for friends and other independent Plex accounts.

### Optional: whitelisting (libraries)

If you don’t see your libraries:

1. Click **Load Libraries**.
2. Pick the libraries you want CrossWatch to use.
3. Click **Save**.

Guide: [Library Whitelisting](/crosswatch/library-whitelisting.md).

### Troubleshooting

* If the Plex auth tab doesn’t open, disable popup blockers for CrossWatch.
* If Plex server calls fail, make sure the PMS URL is reachable from the CrossWatch container.
* Prefer a LAN IP while debugging (example: `http://192.168.1.1:32400`).
  {% endtab %}

{% tab title="Power users" %}

### Config keys

Stored under:

* `plex.*`

Common keys:

* `plex.account_token`
* `plex.server_id` / `plex.account_id` (when present)

### Related docs

* Sync module: [PLEX module](/blueprint-architecture/sync/_mod_plex.md)
* Adapter: [Adapter: Plex](/crosswatch/providers/synchronization/adapter-plex.md)
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/providers/authentication/auth-media-servers/auth-plex.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.