> ## 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

> Three flows — OAuth 2.0 for server-side web apps, Public PKCE for mobile and SPAs, PIN for TVs and CLIs. Pick one and you're 5 minutes from your first authenticated call.

Every Simkl API call that touches a user's data needs a per-user `access_token`. Tokens are long-lived — the success response advertises `expires_in: 157680000` (5 years), and in practice tokens remain valid until the user revokes your app from [Connected Apps settings](https://simkl.com/settings/connected-apps/). Simkl gives you three ways to obtain a token. They're all variants of OAuth 2.0 from the user's perspective, but the integration story is very different. Pick the flow that matches the device your app runs on.

<CardGroup cols={3}>
  <Card title="OAuth 2.0" icon="lock" href="/api-reference/oauth">
    For **server-side web apps** that can keep a `client_secret`. The user logs in via their browser; your backend exchanges the `code` for a token. \~5 seconds end-to-end.
  </Card>

  <Card title="Public PKCE" icon="shield-keyhole" href="/api-reference/oauth-pkce">
    For **mobile, SPA, browser extensions, desktop binaries** — any client where you can't safely embed `client_secret`. Same browser-based UX, no secret required.
  </Card>

  <Card title="PIN flow" icon="qrcode" href="/api-reference/pin">
    For **TVs, consoles, watches, CLIs, and media-server plugins** — anywhere typing a URL is hard. Show a 5-character code; the user enters it on their phone.
  </Card>
</CardGroup>

## At a glance

|                           | OAuth 2.0                           | Public PKCE                                                                    | PIN                                   |
| ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- |
| **Best for**              | Server-side web apps                | Mobile, SPA, browser extensions, desktop binaries                              | TVs, consoles, watches, CLIs, plugins |
| **Time to token**         | \~5 seconds                         | \~5 seconds                                                                    | 30 seconds – 2 minutes                |
| **Needs `client_secret`** | Yes                                 | **No** — uses `code_verifier` + `code_challenge`                               | No                                    |
| **Needs `redirect_uri`**  | Yes (pre-registered, byte-for-byte) | Yes, OR omit if no redirect URI is registered (consent completes on simkl.com) | No                                    |

## Get an API key first

All three flows require a `client_id`. [Create an app](https://simkl.com/settings/developer/) — free, no approval required. Confidential clients also receive a `client_secret`; public clients can ignore it.

<Warning>
  **Never embed `client_secret` in client-side code.** Mobile apps, single-page apps, browser extensions, and desktop binaries should use [Public PKCE](/api-reference/oauth-pkce) or the [PIN flow](/api-reference/pin) — both work without a secret.
</Warning>

## Full walkthrough

The complete reference — platform recommendations, multi-language code samples, common pitfalls, token lifecycle — lives in the API Reference:

<CardGroup cols={1}>
  <Card title="Auth — full guide and code samples" icon="shield-halved" href="/api-reference/auth">
    Per-platform recommendations (iOS, Android, web, desktop, TV, headless), step-by-step OAuth and PIN walkthroughs with curl/Swift/Kotlin/Node/Python samples, common pitfalls, and token lifecycle in one page.
  </Card>
</CardGroup>

## Endpoint reference

<CardGroup cols={3}>
  <Card title="OAuth 2.0 endpoints" icon="lock" href="/api-reference/oauth">
    `GET /oauth/authorize` and `POST /oauth/token`.
  </Card>

  <Card title="Public PKCE walkthrough" icon="shield-keyhole" href="/api-reference/oauth-pkce">
    PKCE flow ([RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)) with per-platform recipes.
  </Card>

  <Card title="PIN endpoints" icon="qrcode" href="/api-reference/pin">
    `GET /oauth/pin` and `GET /oauth/pin/{USER_CODE}`.
  </Card>
</CardGroup>

## Before you reach for an OAuth library

<Note>
  **Both content-types and both credential locations work.** Simkl's `POST /oauth/token` accepts:

  * `Content-Type: application/x-www-form-urlencoded` (the RFC 6749 §3.2 default) **or** `Content-Type: application/json` — pick whichever your HTTP client prefers
  * Client credentials in the request body (`client_id` + `client_secret` parameters) **or** in the `Authorization: Basic` header (RFC 6749 §2.3.1) — both paths are honored

  That means **off-the-shelf OAuth libraries work out-of-the-box** with no custom encoding or auth-method config. The two equivalent ways to call the token endpoint:

  <CodeGroup>
    ```bash form-encoded (RFC 6749 §3.2 default) theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST https://api.simkl.com/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -H "User-Agent: my-app-name/1.0" \
      --data-urlencode "client_id=YOUR_CLIENT_ID" \
      --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
      --data-urlencode "code=AUTHORIZATION_CODE" \
      --data-urlencode "redirect_uri=YOUR_REDIRECT_URI" \
      --data-urlencode "grant_type=authorization_code"
    ```

    ```bash JSON body theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST https://api.simkl.com/oauth/token \
      -H "Content-Type: application/json" \
      -H "User-Agent: my-app-name/1.0" \
      -d '{
        "client_id":     "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "code":          "AUTHORIZATION_CODE",
        "redirect_uri":  "YOUR_REDIRECT_URI",
        "grant_type":    "authorization_code"
      }'
    ```
  </CodeGroup>

  For library-specific examples (Python, Node, Java, Go, PHP), see [OAuth client libraries](/api-reference/oauth-libraries) — most are zero-config.
</Note>