SIMKL

End users

SIMKL is also used for scrobbling (Watcher/Webhooks) when configured.

Connect SIMKL

Connect with PIN

PIN is the recommended method. It does not need a SIMKL developer app.

1. Open CrossWatch.
2. Go to Settings → Connections → Authentication → SIMKL.
3. Select PIN.
4. Click Connect SIMKL.
5. CrossWatch shows a short authorization code.
6. Enter the code at SIMKL PIN.
7. Approve the connection.
8. Return to CrossWatch.

CrossWatch checks the authorization status automatically. It then shows Connected using PIN.

CrossWatch opens the SIMKL PIN page in a new browser tab. If blocked, open SIMKL PIN manually.

If the code expires, click Restart and repeat the authorization.

Connect with OAuth

OAuth is optional. Use it with your own SIMKL developer app.

1. Open SIMKL developer settings.
2. Click Add → Add a new App.
3. Set Name and Description to CrossWatch.
4. Set Redirect URI to the callback URL shown by CrossWatch. For example: http://<your-server-ip>:8787/callback.
5. Click Save Changes.
6. Copy the Client ID and Client Secret into CrossWatch.
7. Select OAuth, then click Connect SIMKL.
8. Approve the connection in SIMKL.

If you change the host, port, or protocol, update the OAuth Redirect URI.

See HTTPS/TLS.

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 PIN page does not open, allow popups for CrossWatch.
• If the PIN expires, click Restart to get a new code.
• If OAuth fails, verify that 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.

Power users