Request a PIN code

curl --request GET \
  --url https://api.simkl.com/oauth/pin \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'

import requests

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

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', 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', 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")
  .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")!
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';
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"

	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");
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");
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",
  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")

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

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");

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");

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": "OK",
  "device_code": "DEVICE_CODE",
  "user_code": "5G6JAH",
  "verification_uri": "https://simkl.com/pin",
  "verification_url": "https://simkl.com/pin",
  "expires_in": 900,
  "interval": 5
}

{
  "error": "forbidden",
  "code": 403
}

Request a PIN code

Step 1 of the PIN flow (also called the device flow). Best for TVs, consoles, smart watches, CLI tools — anywhere typing a URL is hard. You don’t need client_secret for this flow.

The response contains a 5-character user_code to display, a verification_uri for the user to visit, an expires_in lifetime (15 minutes), and an interval you must respect when polling (5 seconds).

Parameters

Param	Required	Notes
`client_id`	yes	Sent as `?client_id=…` URL query parameter. The `simkl-api-key` header is also accepted but the URL-parameter form is preferred.
`redirect`	no	URL the simkl.com/pin page sends the user to after they approve. Must match a URL pre-registered in your app’s developer settings. Mostly relevant for browser-extension and web-flavoured PIN integrations.

About the `device_code` response field

The response includes a device_code field whose value is the literal string "DEVICE_CODE" — it’s a placeholder kept for compatibility with the OAuth 2.0 Device Authorization Grant response shape. Clients only need user_code (what you display, and what you poll on). You can ignore device_code entirely.

Not the RFC 8628 device flow. Simkl’s PIN flow is conceptually similar to RFC 8628 (OAuth Device Authorization Grant) but the wire format differs in several spots:

device_code is a hardcoded placeholder, not a real opaque token.
Polling happens at GET /oauth/pin/{user_code} instead of POST /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code.
Pending poll responses are {"result": "KO", "message": "Authorization pending"} instead of 400 + {"error": "authorization_pending"}.

Generic device-flow libraries (e.g. openid-client device-flow extension) won’t work out of the box. Either write a custom client for the wire format above, or follow the PIN flow walkthrough which uses the documented endpoints directly.

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.

GET

oauth

Request a PIN code

curl --request GET \
  --url https://api.simkl.com/oauth/pin \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'

import requests

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

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', 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', 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")
  .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")!
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';
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"

	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");
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");
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",
  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")

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

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");

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");

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": "OK",
  "device_code": "DEVICE_CODE",
  "user_code": "5G6JAH",
  "verification_uri": "https://simkl.com/pin",
  "verification_url": "https://simkl.com/pin",
  "expires_in": 900,
  "interval": 5
}

{
  "error": "forbidden",
  "code": 403
}

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

Query Parameters

client_id

string

required

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

redirect

string

URL the simkl.com/pin page sends the user to after they approve the connection. Must match a URL pre-registered in your app settings. Optional — most PIN-flow clients (TVs, consoles, CLIs) don't need this since the user authorizes on a separate device and the app polls for the result.

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

Step 1 response from GET /oauth/pin. Display user_code, point the user at verification_uri, and poll GET /oauth/pin/{user_code} every interval seconds until expires_in elapses.

result

string

Example:

"OK"

device_code

string

user_code

string

Example:

"5G6JAH"

verification_uri

string

Where the user enters user_code. RFC 8628 §3.2 spelling. Read this field.

Example:

"https://simkl.com/pin"

verification_url

string

Alias for verification_uri — same value, kept for back-compat. New code should read verification_uri.

Example:

"https://simkl.com/pin"

expires_in

integer

Example:

900

interval

integer

Example:

5

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

Request a PIN code

Parameters

About the `device_code` response field

PIN flow walkthrough

Authorizations

Headers

Query Parameters

Response