> 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/settings/connections/library-whitelisting.md).

# Library Whitelisting

Control which Plex, Jellyfin, and Emby libraries CrossWatch reads, writes, synchronizes, and scrobbles.

Whitelisting reduces unnecessary processing and prevents CrossWatch from operating on libraries that are outside the intended sync scope.

{% hint style="info" %}
An empty whitelist disables filtering for that category.

CrossWatch allows all libraries visible to the configured user.

CrossWatch only blocks other libraries after you select one or more libraries.
{% endhint %}

Use whitelisting to:

* Reduce API calls
* Improve sync performance
* Exclude unrelated libraries, such as music, photos, or live TV
* Limit History, Ratings, and Progress synchronization
* Prevent scrobbling from selected libraries

<figure><img src="/files/9cnUl2kosLXauy2HiG66" alt=""><figcaption></figcaption></figure>

### Whitelist levels

CrossWatch supports two whitelist levels.

#### Server level whitelisting

Server level whitelisting is configured in the provider authentication settings.

It applies to every pair that uses the selected provider profile.

Server level whitelisting is available for:

* History, H
* Ratings, R
* Progress, P
* Scrobble, S

The server level whitelist defines the maximum scope available to CrossWatch.

#### Pair level whitelisting

Pair level whitelisting is configured in the pair editor.

It applies only to the selected pair and is available for:

* History
* Ratings
* Progress

Pair level whitelisting lets you reduce the scope of an individual pair without changing other pairs that use the same provider profile.

Scrobble whitelisting is only available at server level because scrobbling is event driven and is not processed through sync pairs.

### How the levels interact

Server level whitelisting defines the maximum permitted scope.

Pair level whitelisting defines the subset used by a specific pair.

For example, when the server level History whitelist contains Movies and TV Shows, the pair editor only offers Movies and TV Shows for History.

A pair cannot select a library that is excluded by the server level whitelist.

When the server level whitelist for a feature is empty, filtering is disabled for that feature.

All visible libraries remain available to pairs.

When one or more libraries are selected, only those libraries are allowed and the rest are blocked.

### Recommended configuration

Use server level whitelisting for the default scope of a provider profile.

Use pair level whitelisting when an individual pair requires a smaller scope.

Example:

Server level History:

* Movies
* TV Shows

Pair A History:

* Movies

Pair B History:

* TV Shows

Both pairs remain within the maximum server level scope.

### Server level whitelisting

Server level whitelisting is available for Plex, Jellyfin, and Emby under:

**Settings → Connections → Authentication → Provider → Whitelisting**

When Profiles, also called Instances, are enabled, whitelisting is configured separately for each profile.

Each profile has its own server connection, user, and library selections.

#### Configure server level whitelisting

{% stepper %}
{% step %}

### Open the provider

Go to **Settings → Connections → Authentication**.

Open **Plex**, **Jellyfin**, or **Emby**.
{% endstep %}

{% step %}

### Select a profile

Select the provider profile you want to configure.

Whitelists belong to the selected profile and do not affect other profiles.
{% endstep %}

{% step %}

### Open Whitelisting

Open the **Whitelisting** section.
{% endstep %}

{% step %}

### Load libraries

Select **Load Libraries**.

CrossWatch retrieves the libraries available to the configured server and user.

Emby and Jellyfin expose libraries as views.

CrossWatch resolves media items to their corresponding view before applying the whitelist.
{% endstep %}

{% step %}

### Select libraries

Select the libraries allowed for each feature:

* H, History
* R, Ratings
* P, Progress
* S, Scrobble
  {% endstep %}

{% step %}

### Save

Save the provider settings.

The selected libraries become the maximum available scope for all pairs using this provider profile.
{% endstep %}
{% endstepper %}

### Pair level whitelisting

Pair level whitelisting is available in the pair editor for Plex, Jellyfin, and Emby.

Pair selections are stored per feature and per provider.

#### Configure pair level whitelisting

{% stepper %}
{% step %}

### Open the pair

Go to **Pairs** and edit the required pair.
{% endstep %}

{% step %}

### Open a feature

Open **History**, **Ratings**, or **Progress**.
{% endstep %}

{% step %}

### Load libraries

Open the Plex, Jellyfin, or Emby provider settings in the pair editor.

Select **Load Libraries** when the libraries have not already loaded automatically.

CrossWatch only displays libraries permitted by the server level whitelist for the selected feature.
{% endstep %}

{% step %}

### Select libraries

Select the libraries that this pair may use for the current feature.

Library selections are independent for History, Ratings, and Progress.
{% endstep %}

{% step %}

### Save

Save the pair and run it again.
{% endstep %}
{% endstepper %}

### Progress whitelisting

Progress whitelisting controls which libraries participate in resume position synchronization.

It can be configured at both levels:

* Server level, defines the maximum Progress scope for a provider profile
* Pair level, defines the Progress scope for one pair

Progress selections are independent from History selections.

Selecting a library for History does not automatically select it for Progress.

### Scrobble whitelisting

Scrobble whitelisting controls which libraries can generate real time scrobble events.

It applies to:

* Watchers
* Webhooks

Scrobble filtering is allow list based.

When the Scrobble whitelist is empty, scrobble filtering is disabled.

CrossWatch accepts events from all visible libraries.

When one or more libraries are selected, CrossWatch only accepts events that can be resolved to one of those library identifiers.

Events from other libraries are blocked.

When a whitelist is configured but an event does not contain a usable library identifier, CrossWatch skips the event.

There is no separate scrobble library blacklist.

### Dashboards and Insights

Some dashboards use orchestrator state rather than the final per pair adapter scope.

Server level whitelisting is therefore recommended for global filtering.

Pair level filtering can make some dashboard totals appear larger than the data actually processed by an individual pair.

Use server level whitelisting when dashboard scope must match the overall sync scope.

### Troubleshooting

#### The pair editor shows fewer libraries than expected

Check the server level whitelist for the same provider profile and feature.

The pair editor only displays libraries permitted by the server level whitelist.

Clear the server level selection for that feature to make all visible libraries available.

#### Pair level whitelisting is not applied

Confirm that libraries are selected under the correct provider and feature.

History, Ratings, and Progress have separate library selections.

Save the pair and run it again.

#### Progress synchronization includes the wrong library

Check both the server level Progress whitelist and the pair level Progress whitelist.

Do not rely on the History whitelist, because History and Progress use separate selections.

#### Scrobbling ignores the pair selection

This is expected.

Scrobble whitelisting is configured only at server level.

Verify the S selection under the provider profile Whitelisting settings.

#### Scrobble events are skipped

When a Scrobble whitelist is configured, CrossWatch must resolve the event to an allowed library.

Events without a usable library identifier are rejected.

Check the watcher or webhook logs for library resolution details.

#### Insights shows too much data

Insights may use orchestrator state before pair level adapter filtering is applied.

Use server level whitelisting for global scope and pair level whitelisting only for pair specific exceptions.

### Reset whitelisting

To allow all visible libraries again:

1. Open the provider profile under **Settings → Connections → Authentication**.
2. Clear the selected H, R, P, and S libraries.
3. Save the provider settings.
4. Open each affected pair.
5. Clear its History, Ratings, and Progress library selections.
6. Save and run the pair again.

An empty whitelist means filtering is disabled and all visible libraries are allowed.

### Related topics

* [Profiles](/crosswatch/settings/connections/profiles.md)
* [Pair-level Whitelisting](/crosswatch/settings/configure-pairs/provider-settings/pair-level-whitelisting.md)
* [Filters](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/PH2jfcZjseHr6sFkoKAP)
* [Progress](/crosswatch/settings/configure-pairs/features/progress.md)


---

# 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, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/library-whitelisting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.