API Reference
Trending
Calendar
Redirect
Sync
Changes
curl --request GET \
--url https://simkl.com/oauth/authorize \
--header 'User-Agent: <user-agent>' \
--header 'simkl-api-key: <api-key>'Step 1 of the OAuth 2.0 authorization-code flow. Redirect the user’s browser to this URL on simkl.com (not api.simkl.com). Simkl shows a consent screen and, once the user approves, redirects to your redirect_uri with ?code=….
⚠️ Do not use a WebView on mobile. Use the system browser or a Custom Tab. WebViews are blocked for security reasons.
Parameters
| Param | Required | Notes |
|---|---|---|
response_type | yes | Must be code. |
client_id | yes | Your app’s client_id. |
redirect_uri | conditional | Required for confidential clients and for any app that has a redirect URI registered. Optional only when using PKCE and your app has no registered redirect URI — in that case Simkl completes the consent flow on simkl.com itself. When sent, must match the URL registered for the app byte-for-byte. |
state | no | Random string you generate; echoed back to your redirect_uri for CSRF protection. Strongly recommended. |
code_challenge | conditional | Required for PKCE (public clients without client_secret). Base64url-encoded SHA-256 of your code_verifier. See the Public PKCE walkthrough. |
code_challenge_method | no | S256 (default, recommended) or plain. Case-sensitive — lowercase variants are silently ignored and your token exchange will then fail with Wrong Secret. |
The user is redirected to:
YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE
Exchange the code for an access_token via POST /oauth/token. Codes are short-lived; exchange immediately.
OAuth 2.0 walkthrough
Confidential-client (server-side) flow with client_secret.
Public PKCE walkthrough
Public-client (mobile / SPA / desktop) flow with code_verifier + code_challenge.
curl --request GET \
--url https://simkl.com/oauth/authorize \
--header 'User-Agent: <user-agent>' \
--header 'simkl-api-key: <api-key>'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.
Authorizations
Optional alias for the client_id query parameter. Simkl accepts your client_id either as the simkl-api-key request header or as the ?client_id=… query parameter — pick one. The query-parameter form is preferred because it makes the request fully self-describing in URL form.
Headers
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Query Parameters
must be "code"
Your client_id from your Simkl developer settings. Required on every request.
Where Simkl sends the user back after they approve consent. Must match a URI pre-registered in your app settings byte-for-byte (scheme, host, port, path, trailing slash, casing — all of it). Required for confidential-client flows. Optional when using PKCE and your app has no registered redirect URI — in that case the consent page completes the flow on simkl.com directly.
Random string you generate; Simkl echoes it back unchanged on the redirect to your redirect_uri. Use this for CSRF protection — verify on the redirect that the value matches what you originally sent. Strongly recommended for browser-based clients.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
PKCE code challenge — base64url-encoded SHA-256 hash of the code verifier. Required for the PKCE flow (mobile/desktop/SPA clients without client_secret). Pair with the matching code_verifier when exchanging at POST /oauth/token.
Hash method used to derive code_challenge. S256 (SHA-256, default) is recommended; plain is accepted for legacy clients but discouraged.
S256, plain Response
User approved. Browser is redirected to redirect_uri?code=…&state=…. Exchange the code immediately via POST /oauth/token.
Was this page helpful?