Device authorization (V2)

curl --request POST \
  --url https://api.simkl.com/oauth2/device \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=YOUR_CLIENT_ID

import requests

url = "https://api.simkl.com/oauth2/device"

payload = { "client_id": "YOUR_CLIENT_ID" }
headers = {"Content-Type": "application/x-www-form-urlencoded"}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams({client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/device', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams({client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/device', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/x-www-form-urlencoded")
val body = RequestBody.create(mediaType, "client_id=YOUR_CLIENT_ID")
val request = Request.Builder()
  .url("https://api.simkl.com/oauth2/device")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build()

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

import Foundation

let parameters = [
  "client_id": "YOUR_CLIENT_ID",
]
let joinedParameters = parameters.map { "\($0.key)=\($0.value)" }.joined(separator: "&")
let postData = Data(joinedParameters.utf8)

let url = URL(string: "https://api.simkl.com/oauth2/device")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = ["Content-Type": "application/x-www-form-urlencoded"]
request.httpBody = postData

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

const encodedParams = new URLSearchParams();
encodedParams.set('client_id', 'YOUR_CLIENT_ID');

const url = 'https://api.simkl.com/oauth2/device';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: encodedParams
};

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

package main

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

func main() {

	url := "https://api.simkl.com/oauth2/device"

	payload := strings.NewReader("client_id=YOUR_CLIENT_ID")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	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/oauth2/device");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("client_id", "YOUR_CLIENT_ID");
var response = await client.PostAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth2/device");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("client_id", "YOUR_CLIENT_ID");
var response = await client.PostAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/oauth2/device",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "client_id=YOUR_CLIENT_ID",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$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/oauth2/device")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "client_id=YOUR_CLIENT_ID"

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

$headers=@{}
$headers.Add("Content-Type", "application/x-www-form-urlencoded")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/oauth2/device' -Method POST -Headers $headers -ContentType 'application/x-www-form-urlencoded' -Body 'client_id=YOUR_CLIENT_ID'

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth2/device");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth2/device");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

{
  "device_code": "EXAMPLEDEVICECODE00000000000000000000000000000000000000000000000",
  "user_code": "BDWP-HQPK",
  "verification_uri": "https://simkl.com/pin",
  "verification_uri_complete": "https://simkl.com/pin?user_code=BDWP-HQPK",
  "expires_in": 900,
  "interval": 5
}

{
  "error": "invalid_client",
  "error_description": "This client_id is not enabled for OAuth 2.0"
}

Device authorization (V2)

Starts the RFC 8628 device flow for input-constrained devices — TVs, consoles, set-top boxes, CLIs.

Show the returned user_code to the user and send them to verification_uri, then poll POST /oauth2/token with the device_code and grant_type=urn:ietf:params:oauth:grant-type:device_code.

The user_code is 8 characters, displayed as XXXX-YYYY. Entry is forgiving: it is case-insensitive, hyphens and spaces are optional, and the letters I, L and O are accepted in place of 1, 1 and 0. You do not need to validate the user’s typing yourself.

Requires a client_id registered for OAuth V2. An AUTH V1 app cannot use this endpoint and is rejected with invalid_client.

Omitting scope grants media:read only.

Body format

Both application/x-www-form-urlencoded (the RFC 6749 section 3.2 default) and application/json are accepted. Every parameter must be a plain string. Sending an array or object for any parameter returns 400 invalid_request naming the offending parameter.

Every /oauth2/* response is sent with Cache-Control: no-store and Pragma: no-cache. Do not cache these responses, including the errors.

POST

oauth2

device

Device authorization (V2)

curl --request POST \
  --url https://api.simkl.com/oauth2/device \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=YOUR_CLIENT_ID

import requests

url = "https://api.simkl.com/oauth2/device"

payload = { "client_id": "YOUR_CLIENT_ID" }
headers = {"Content-Type": "application/x-www-form-urlencoded"}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams({client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/device', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams({client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/device', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/x-www-form-urlencoded")
val body = RequestBody.create(mediaType, "client_id=YOUR_CLIENT_ID")
val request = Request.Builder()
  .url("https://api.simkl.com/oauth2/device")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build()

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

import Foundation

let parameters = [
  "client_id": "YOUR_CLIENT_ID",
]
let joinedParameters = parameters.map { "\($0.key)=\($0.value)" }.joined(separator: "&")
let postData = Data(joinedParameters.utf8)

let url = URL(string: "https://api.simkl.com/oauth2/device")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = ["Content-Type": "application/x-www-form-urlencoded"]
request.httpBody = postData

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

const encodedParams = new URLSearchParams();
encodedParams.set('client_id', 'YOUR_CLIENT_ID');

const url = 'https://api.simkl.com/oauth2/device';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: encodedParams
};

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

package main

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

func main() {

	url := "https://api.simkl.com/oauth2/device"

	payload := strings.NewReader("client_id=YOUR_CLIENT_ID")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	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/oauth2/device");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("client_id", "YOUR_CLIENT_ID");
var response = await client.PostAsync(request);

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

using RestSharp;


var options = new RestClientOptions("https://api.simkl.com/oauth2/device");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("client_id", "YOUR_CLIENT_ID");
var response = await client.PostAsync(request);

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.simkl.com/oauth2/device",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "client_id=YOUR_CLIENT_ID",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$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/oauth2/device")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "client_id=YOUR_CLIENT_ID"

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

$headers=@{}
$headers.Add("Content-Type", "application/x-www-form-urlencoded")
$response = Invoke-WebRequest -Uri 'https://api.simkl.com/oauth2/device' -Method POST -Headers $headers -ContentType 'application/x-www-form-urlencoded' -Body 'client_id=YOUR_CLIENT_ID'

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth2/device");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_WRITEDATA, stdout);
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.simkl.com/oauth2/device");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

{
  "device_code": "EXAMPLEDEVICECODE00000000000000000000000000000000000000000000000",
  "user_code": "BDWP-HQPK",
  "verification_uri": "https://simkl.com/pin",
  "verification_uri_complete": "https://simkl.com/pin?user_code=BDWP-HQPK",
  "expires_in": 900,
  "interval": 5
}

{
  "error": "invalid_client",
  "error_description": "This client_id is not enabled for OAuth 2.0"
}

Body

application/x-www-form-urlencoded

client_id

string

required

Your app's client ID.

scope

enum<string>

Defaults to media:read when omitted.

Available options:

media:read,

media:read media:write

Response

Device authorization started.

RFC 8628 section 3.2 device authorization response.

device_code

string

required

Secret handle the device polls with. Never show this to the user.

user_code

string

required

The 8-character code the user types, formatted XXXX-YYYY. Display it exactly as returned.

Example:

"BDWP-HQPK"

verification_uri

string

required

Where the user goes to enter the code.

Example:

"https://simkl.com/pin"

verification_uri_complete

string

required

The same page with the code pre-filled. Ideal for a QR code, since the user then types nothing.

Example:

"https://simkl.com/pin?user_code=BDWP-HQPK"

expires_in

integer

required

Seconds until the device code expires. 900, i.e. 15 minutes.

Example:

900

interval

integer

required

Minimum seconds between polls. 5.

Example:

5

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Device authorization (V2)

Body format

Body

Response