Poll PIN code 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>'

import requests

url = "https://api.simkl.com/oauth/pin/{user_code}"

headers = {
    "User-Agent": "<user-agent>",
    "simkl-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/oauth/pin/{user_code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/oauth/pin/{user_code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/oauth/pin/{user_code}")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("simkl-api-key", "<api-key>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/oauth/pin/{user_code}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "simkl-api-key": "<api-key>"
]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

const url = 'https://api.simkl.com/oauth/pin/{user_code}';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/oauth/pin/{user_code}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("simkl-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth/pin/{user_code}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth/pin/{user_code}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/oauth/pin/{user_code}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "User-Agent: <user-agent>",
    "simkl-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/oauth/pin/{user_code}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["simkl-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("simkl-api-key", "<api-key>")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/oauth/pin/{user_code}' -Method GET -Headers $headers

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth/pin/{user_code}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth/pin/{user_code}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "result": "KO",
  "message": "Authorization pending"
}

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.

GET

oauth

{user_code}

Poll PIN code 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>'

import requests

url = "https://api.simkl.com/oauth/pin/{user_code}"

headers = {
    "User-Agent": "<user-agent>",
    "simkl-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/oauth/pin/{user_code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch('https://api.simkl.com/oauth/pin/{user_code}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.simkl.com/oauth/pin/{user_code}")
  .get()
  .addHeader("User-Agent", "<user-agent>")
  .addHeader("simkl-api-key", "<api-key>")
  .build()

val response = client.newCall(request).execute()

import Foundation

let url = URL(string: "https://api.simkl.com/oauth/pin/{user_code}")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
  "User-Agent": "<user-agent>",
  "simkl-api-key": "<api-key>"
]

let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))

const url = 'https://api.simkl.com/oauth/pin/{user_code}';
const options = {
  method: 'GET',
  headers: {'User-Agent': '<user-agent>', 'simkl-api-key': '<api-key>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simkl.com/oauth/pin/{user_code}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "<user-agent>")
	req.Header.Add("simkl-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth/pin/{user_code}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth/pin/{user_code}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("User-Agent", "<user-agent>");
request.AddHeader("simkl-api-key", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/oauth/pin/{user_code}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "User-Agent: <user-agent>",
    "simkl-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.simkl.com/oauth/pin/{user_code}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = '<user-agent>'
request["simkl-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

$headers=@{}
$headers.Add("User-Agent", "<user-agent>")
$headers.Add("simkl-api-key", "<api-key>")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/oauth/pin/{user_code}' -Method GET -Headers $headers

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth/pin/{user_code}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth/pin/{user_code}");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "User-Agent: <user-agent>");
headers = curl_slist_append(headers, "simkl-api-key: <api-key>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

{
  "result": "KO",
  "message": "Authorization pending"
}

Authorizations

simkl-api-key

string

header

default:YOUR_CLIENT_ID

required

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

User-Agent

string

required

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

user_code

string

required

Get this from previous step

Query Parameters

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

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

result

string

Example:

"OK"

access_token

string

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Poll PIN code for the access token

Possible responses

PIN flow walkthrough

Authorizations

Headers

Path Parameters

Query Parameters

Response