Poll PIN code for the access token
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.
An AUTH V2 client_id cannot use this endpoint. It is refused with 400 unauthorized_client and a message pointing at POST /oauth2/device. A registration is V1 or V2, never both.
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
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.)