API Reference
Trending
Calendar
Redirect
Sync
Changes
curl --request GET \
--url https://api.simkl.com/oauth/pin/{user_code} \
--header 'User-Agent: <user-agent>' \
--header 'simkl-api-key: <api-key>'Step 3 of the PIN flow. Poll this endpoint every interval seconds (returned in step 1, currently 5) to learn whether the user has entered the code. Stop polling when expires_in (currently 900 seconds) elapses and prompt the user to restart.
Possible responses
| Body | Meaning |
|---|---|
{ "result": "OK", "access_token": "…" } | User authorized. Save the token and stop polling. |
{ "result": "KO", "message": "Authorization pending" } | Keep polling at the returned interval. |
After receiving the access_token, send it as Authorization: Bearer <token> on every authenticated request.
Polling a code that doesn’t exist (anymore) returns a fresh init response. If you keep polling after a successful authorization, the server has already deleted the original user_code row and this endpoint falls through to the create-a-new-code branch — you’ll get back the same shape as GET /oauth/pin (with a brand-new user_code different from the one you polled). Treat any response that contains device_code as “the original code is gone” and stop polling. The same thing happens for any unknown user_code (typos, expired codes that have been garbage-collected).
PIN flow walkthrough
Device authorization for TVs, consoles, smart watches, and CLI tools — show a 5-character code, the user enters it at simkl.com/pin, the app polls for the access token.
curl --request GET \
--url https://api.simkl.com/oauth/pin/{user_code} \
--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).
Path Parameters
Get this from previous step
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
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.
Response
PIN poll result. The body shape depends on whether the user has entered the code yet.
- Complete (token issued)
- Pending (waiting for user)
One of two shapes — result: "OK" with access_token when complete, or result: "KO" with "Authorization pending" while waiting. (Polling an unknown / deleted user_code returns a fresh init response shape with a new user_code, same as GET /oauth/pin.)
Was this page helpful?