# Auth: TMDb

TMDb can be used in CrossWatch in two different ways.

* **Metadata (recommended)**: improves matching across providers.\
  Setup guide: [Meta: TMDb](/crosswatch/providers/metadata/meta-tmdb.md).
* **TMDb (Sync)**: connects your TMDb account so CrossWatch can read/write TMDb data.

This page covers **TMDb (Sync)**.

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

### What it supports

* Watchlist
* Ratings

{% hint style="info" %}
If you only want better matching, you want **Metadata → TMDb**, not TMDb (Sync).
{% endhint %}

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

### Connect TMDb (Sync)

{% stepper %}
{% step %}

### Create a TMDb API key (v3)

1. Create a TMDb account.
2. Request an API key: <https://www.themoviedb.org/settings/api>
   {% endstep %}

{% step %}

### Connect in CrossWatch

1. Open **Settings → TMDb (Sync)**.
2. Paste your **TMDb API Key (v3)**.
3. Click **Connect**.
4. A TMDb tab opens. Approve the request.
5. Return to CrossWatch. Wait for “Connected”.

If it stays pending, click **Verify** once.
{% endstep %}
{% endstepper %}

### Disconnect

1. Open **Settings → TMDb (Sync)**.
2. Click **Disconnect**.

### Troubleshooting

* Auth tab didn’t open: disable popup blockers for CrossWatch.
* Stuck on “Pending approval”: approve in the TMDb tab, then click **Verify**.
* “TMDb did not return a session id”: restart the flow with **Connect** and approve again.
* Verify keeps failing: the server must reach `https://api.themoviedb.org/3`.
* Key issues: the key must be a valid TMDb **v3 API key**.

### Security notes

Treat your TMDb **API key** and **session** as secrets.

They are stored in CrossWatch config on disk.
{% endtab %}

{% tab title="Power users" %}

### Config keys used

TMDb (Sync) stores values under:

* `tmdb_sync.api_key`
* `tmdb_sync.session_id`

Metadata stores a separate key under:

* `tmdb.api_key`

### API endpoints (manual flow)

<details>

<summary>Start / Verify / Finish / Disconnect</summary>

CrossWatch exposes a small API used by the UI.

These are useful for debugging or headless setup.

#### Start (opens the approval URL)

`POST /api/tmdb_sync/connect/start`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/connect/start \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY"}'
```

Open the returned `auth_url` and approve.

#### Verify (auto-finish after approval)

`GET /api/tmdb_sync/verify`

```bash
curl http://localhost:PORT/api/tmdb_sync/verify
```

#### Finish (optional explicit completion)

`POST /api/tmdb_sync/connect/finish`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/connect/finish \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY","request_token":"REQUEST_TOKEN"}'
```

#### Disconnect

`POST /api/tmdb_sync/disconnect`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/disconnect
```

</details>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: 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-tmdb.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.