Skip to main content

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.

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

OAuth 2.0

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.

Public 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.

PIN flow

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.

​
At a glance

OAuth 2.0Public PKCEPIN
Best forServer-side web appsMobile, SPA, browser extensions, desktop binariesTVs, consoles, watches, CLIs, plugins
Time to token~5 seconds~5 seconds30 seconds – 2 minutes
Needs client_secretYesNo — uses code_verifier + code_challengeNo
Needs redirect_uriYes (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 — free, no approval required. Confidential clients also receive a client_secret; public clients can ignore it.
Never embed client_secret in client-side code. Mobile apps, single-page apps, browser extensions, and desktop binaries should use Public PKCE or the PIN flow — both work without a secret.

​
Full walkthrough

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

Auth — full guide and code samples

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.

​
Endpoint reference

OAuth 2.0 endpoints

GET /oauth/authorize and POST /oauth/token.

Public PKCE walkthrough

PKCE flow (RFC 7636) with per-platform recipes.

PIN endpoints

GET /oauth/pin and GET /oauth/pin/{USER_CODE}.

​
Before you reach for an OAuth library

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:
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"
For library-specific examples (Python, Node, Java, Go, PHP), see OAuth client libraries — most are zero-config.