> 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-trackers/auth-mdblist.md).

# Auth: MDBList

MDBList is a service for building and maintaining movie and TV lists. CrossWatch supports Device Code auth and a legacy API key fallback.

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

### What it supports

* Watchlist
* Ratings
* History

{% hint style="info" %}
Use **Device Code** for new setups. It is the default and recommended auth mode.

**API key** auth still works as a fallback.
{% endhint %}

{% hint style="warning" %}
MDBList does not provide easy rollback/export for user data. Use deletes carefully, and consider using [Adapter: CrossWatch](/crosswatch/providers/synchronization/adapter-crosswatch.md) as a safety net.
{% endhint %}

### Connect MDBList with Device Code

1. Open **Settings → Authentication → MDBList**.
2. Set **Authentication Method** to **Device Code**.
3. Click **Connect MDBList**.
4. A browser window opens so you can enter your code.
5. Copy the **Link code (PIN)** from CrossWatch.
6. Paste the code into MDBList.
7. Wait until CrossWatch shows **Connected with Device Code**.

### Use the legacy API key mode

1. Open <https://mdblist.com/preferences/#api>
2. Create or copy your MDBList API key.
3. In CrossWatch, set **Authentication Method** to **API key**.
4. Paste the API key into CrossWatch.
5. Click **Connect MDBList**.

### Troubleshooting

* If the auth window does not open, disable popup blockers for CrossWatch.
* If the link code fails, click **Connect MDBList** again to generate a new code.
* If you use API key mode and auth fails, regenerate the key and reconnect.
* If writes fail, verify items have stable IDs (TMDb/IMDb) in the source provider.
* If you see `429 Too Many Requests`, lower MDBList rate limits.\
  Guide: [Provider rate limiting](/crosswatch/provider-rate-limiting.md).
  {% endtab %}

{% tab title="Power users" %}

### Auth modes

* `Device Code` — recommended
* `API key` — legacy fallback

### Config keys

Stored under:

* `mdblist.rate_limit.get_per_sec`, `mdblist.rate_limit.post_per_sec`
* `mdblist.api_key` when you use legacy API key auth

CrossWatch stores the MDBList token automatically when you use Device Code auth.

Rate-limit defaults and tuning: [Provider rate limiting](/crosswatch/provider-rate-limiting.md)

### Related docs

* Sync module: [MDBList module](/blueprint-architecture/sync/_mod_mdblist.md)
* Adapter: [Adapter: MDBList](/crosswatch/providers/synchronization/adapter-mdblist.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-trackers/auth-mdblist.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.