Skip to main content
Every Simkl API call that touches a user’s data needs a per-user access_token. Public catalog lookups do not, but everything else — watchlist, history, ratings, lists, scrobbling — does. Getting one takes four decisions, and they are all on one page.

Set up authentication

Start here. Pick a client type, work out whether you need a client_secret, pick a flow, choose a scope — in that order, with the consequences of each spelled out.

​
The short version

Use AUTH V2. It is standards-compliant OAuth 2.0, so a stock OAuth library works against it without Simkl-specific handling. There are two flows, and which one you use is decided by what the device can do:

OAuth flow

Web, mobile, SPA, desktop, extensions — anything that can open a browser.

Device / PIN flow

TVs, consoles, watches, CLIs, media-server plugins — anything that cannot. Show an 8-character code, the user approves it on their phone.
Both require PKCE. Your client_id is public and safe to commit; only the secret and user tokens need protecting.
Register the app first — every flow needs a client_id. Create one: free and no approval needed, with 3 unverified apps on Free (more on PRO and VIP), counted separately for V1 and V2.The form asks you to choose a client type, and that choice is permanent. Set up authentication explains what the type decides before you commit to one.

​
Already on AUTH V1?

AUTH V1 is being retired. Plan to migrate.V1 apps are expected to stop working around April 2027 — about six months after the AUTH V2 release. The exact date is not fixed yet, and we will announce it here and in the Discord #api channel with notice — but do not wait for that announcement to start. Everything you need is in Migrating from V1 to V2, and for most apps the work is confined to your auth code.That window should be comfortable for almost everyone. If it is not comfortable for you, tell us rather than running out of time. We can help with the transition, raise your limits while you run both, or extend your timeline if your situation genuinely needs it. Reach us in the Discord #api channel or through support.If something about your integration makes migrating look impossible, that is exactly the case we want to hear about. The goal is for this to be painless for you and invisible to your users.
A V1 client_id cannot be upgraded — V2 is a separate registration with a new client_id, and V1 credentials are rejected by the /oauth2/* endpoints. Your V1 app keeps working while you migrate, so both can run side by side. Start at Migrating from V1 to V2 — what changes, what does not, and the order to do it in.

​
Reference

Set up authentication

Client type, secret, flow, scope — the decisions, in order.

AUTH V2 overview

Anonymous limits, token lifetimes, discovery, and the endpoint reference.

Scopes

media:read and media:write. Omitting scope gives you read-only.

Tokens and refresh

Access tokens last 7 days; refresh tokens last 180 and reset each time you use them.

Migrating from V1

What changes, what does not, and the order to do it in.

Errors

Every error code, including the two different 401s.