> 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-simkl.md).

# Auth: SIMKL

SIMKL is a tracker for movies, shows, and anime. CrossWatch connects via OAuth (client ID/secret + access token).

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

### What it supports

* Watchlist
* Ratings (movies/shows/anime)
* History

{% hint style="info" %}
SIMKL is also used for scrobbling (Watcher/Webhooks) when configured.
{% endhint %}

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

### Connect SIMKL

1. Create a SIMKL developer app:
   1. Open <https://simkl.com/settings/developer/>
   2. Click **Add** → **Add a new App**
   3. Set **Name**: `CrossWatch`
   4. Set **Description**: `CrossWatch`
   5. Set **Redirect URI**: the callback URL shown by CrossWatch, for example: `http://<your-server-ip>:8787/callback`
   6. Click **Save Changes**
2. Copy the **Client ID** and **Client Secret** into CrossWatch.
3. Click **Connect SIMKL**. A new tab opens.
4. Click **YES** to approve.
5. Wait until you see:

   <figure><img src="/files/GwFk9V3vpNxlWQKUIEm2" alt="" width="375"><figcaption></figcaption></figure>

```
SIMKL authorized. You can close this tab and return to the app.
```

{% hint style="warning" %}
If you later switch CrossWatch from **HTTP ↔ HTTPS** (or change host/port), update the SIMKL **Redirect URI** to match.

Guide: [HTTPS/TLS](/crosswatch/navigation/ui-settings/user-interface/https-tls.md).
{% endhint %}

### Limitations

* Watchlist: stable up to \~2,500 items total (max 10,000)
* History (plays): stable up to \~10,000 play events total.
* Ratings: stable up to \~10,000 ratings total.

Prefer incremental windows for big backfills.

### Troubleshooting

* If the auth tab doesn’t open, disable popup blockers for CrossWatch.
* If authorization fails, verify the redirect URI matches exactly.
* If you run sync very often, SIMKL may throttle you. Daily is usually enough.
* If you see `429 Too Many Requests`, tune provider throttling.\
  Guide: [Provider rate limiting](/crosswatch/provider-rate-limiting.md).
  {% endtab %}

{% tab title="Power users" %}

### Config keys

Stored under:

* `simkl.*`

Common keys:

* `simkl.client_id`, `simkl.client_secret`
* `simkl.access_token`

### Related docs

* Sync module: [SIMKL module](/blueprint-architecture/sync/_mod_simkl.md)
* Adapter: [Adapter: SIMKL](/crosswatch/providers/synchronization/adapter-simkl.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-simkl.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.