> ## Documentation Index
> Fetch the complete documentation index at: https://api.simkl.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Every call that touches user data needs a user access token. Start here, then follow the setup page.

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.

<Card title="Set up authentication" icon="shield-halved" href="/api-reference/auth" horizontal>
  **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.
</Card>

## The short version

**Use [AUTH V2](/api-reference/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:

<Columns cols={2}>
  <Card title="OAuth flow" icon="lock" href="/api-reference/oauth2-authorization-code" horizontal>
    **Web, mobile, SPA, desktop, extensions** — anything that can open a browser.
  </Card>

  <Card title="Device / PIN flow" icon="tv" href="/api-reference/oauth2-device" horizontal>
    **TVs, consoles, watches, CLIs, media-server plugins** — anything that cannot. Show an 8-character code, the user approves it on their phone.
  </Card>
</Columns>

Both require PKCE. Your `client_id` is public and safe to commit; only the secret and user tokens need protecting.

<Note>
  **Register the app first** — every flow needs a `client_id`. [Create one](https://simkl.com/settings/developer/): 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](/api-reference/auth#client-types) explains what the type decides before you commit to one.
</Note>

## Already on AUTH V1?

<Warning>
  **AUTH V1 is being retired. [Plan to migrate](/guides/migrating-v1-to-v2).**

  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](https://discord.gg/MJsWNE4) `#api` channel with notice — but do not wait for that announcement to start. Everything you need is in [Migrating from V1 to V2](/guides/migrating-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](https://discord.gg/MJsWNE4) `#api` channel or through [support](/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.
</Warning>

**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](/guides/migrating-v1-to-v2) — what changes, what does not, and the order to do it in.

## Reference

<CardGroup cols={2}>
  <Card title="Set up authentication" icon="shield-halved" href="/api-reference/auth">
    Client type, secret, flow, scope — the decisions, in order.
  </Card>

  <Card title="AUTH V2 overview" icon="shield-check" href="/api-reference/auth-v2">
    Anonymous limits, token lifetimes, discovery, and the endpoint reference.
  </Card>

  <Card title="Scopes" icon="list-check" href="/api-reference/oauth2-scopes">
    `media:read` and `media:write`. Omitting `scope` gives you read-only.
  </Card>

  <Card title="Tokens and refresh" icon="rotate" href="/api-reference/oauth2-tokens">
    Access tokens last 7 days; refresh tokens last 180 and reset each time you use them.
  </Card>

  <Card title="Migrating from V1" icon="arrow-right" href="/guides/migrating-v1-to-v2">
    What changes, what does not, and the order to do it in.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/conventions/errors">
    Every error code, including the two different 401s.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.