Token (V2)

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

import requests

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

payload = {
    "grant_type": "authorization_code",
    "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({grant_type: 'authorization_code', client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/token', 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({grant_type: 'authorization_code', client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/token', 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, "grant_type=authorization_code&client_id=YOUR_CLIENT_ID")
val request = Request.Builder()
  .url("https://api.simkl.com/oauth2/token")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build()

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

import Foundation

let parameters = [
  "grant_type": "authorization_code",
  "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/token")!
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))

HttpResponse<String> response = Unirest.post("https://api.simkl.com/oauth2/token")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("grant_type=authorization_code&client_id=YOUR_CLIENT_ID")
  .asString();

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

const url = 'https://api.simkl.com/oauth2/token';
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/token"

	payload := strings.NewReader("grant_type=authorization_code&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/token");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("grant_type", "authorization_code");
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/token");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("grant_type", "authorization_code");
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/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=authorization_code&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/token")

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 = "grant_type=authorization_code&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/token' -Method POST -Headers $headers -ContentType 'application/x-www-form-urlencoded' -Body 'grant_type=authorization_code&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/token");

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, "grant_type=authorization_code&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/token");

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, "grant_type=authorization_code&client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

{
  "access_token": "simkl_at_EXAMPLEACCESSTOKENVALUE00000000000",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "simkl_rt_EXAMPLEREFRESHTOKENVALUE0000000000",
  "scope": "media:read media:write"
}

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid, expired, or already used"
}

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Token (V2)

Exchanges a grant for an access token. One endpoint serves all three AUTH V2 grants, selected by grant_type:

`grant_type`	Use it to
`authorization_code`	Turn a `code` from the consent redirect into tokens.
`refresh_token`	Get a fresh access token without involving the user.
`urn:ietf:params:oauth:grant-type:device_code`	Poll for approval during the device flow.

This endpoint is on api.simkl.com, while the consent page is on simkl.com. Rather than hardcoding both, a library that reads RFC 8414 metadata can take the single issuer setting https://simkl.com and resolve token_endpoint itself — the same document also advertises all three grants above. See Discovery.

Client authentication

Apps registered as Server apps & services must authenticate. Send the credentials either as an Authorization: Basic header (RFC 6749 section 2.3.1) or as client_id and client_secret parameters in the body. Both are accepted.

Mobile, desktop & browser apps and TV, devices & command line registrations have no secret and send only client_id.

Client authentication is checked before the grant is looked at, and a failure is 401 invalid_client, not 400. If a server app omits its secret it gets invalid_client no matter what else is wrong with the request, which can mask a second problem behind it.

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.

Authorization code grant

Requires code, code_verifier and the same redirect_uri you sent to the authorize endpoint.

The code is consumed the moment it reaches this endpoint, before any validation runs. A wrong code_verifier, a mismatched redirect_uri or a foreign client_id all destroy the code. You cannot correct the request and retry with the same code — the user has to authorize again. Each successful exchange creates a new, independent grant; authorizing a second time does not revoke the first.

Refresh token grant

Requires refresh_token. The same refresh token is returned, with its 180-day window slid forward. The previous access token stops working immediately, so a single grant supports exactly one live access token — two processes sharing one refresh token will keep cutting each other off. Give them separate authorizations.

A scope narrower than the original grant is ignored rather than applied; a wider one is rejected with invalid_scope. A grant’s scope can never shrink.

Device code grant

Requires device_code. Poll no faster than the interval returned by POST /oauth2/device.

authorization_pending — keep polling at the same interval. This is also what you get if the user declined, because declining writes nothing; your own timeout at expires_in is the only signal you will get.
slow_down — add 5 seconds to your interval and wait. The poll timer is reset by the attempt itself, so retrying immediately keeps you permanently rate-limited.
expired_token — the code is dead. Start a new device authorization.

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

POST

oauth2

token

Token (V2)

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

import requests

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

payload = {
    "grant_type": "authorization_code",
    "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({grant_type: 'authorization_code', client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/token', 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({grant_type: 'authorization_code', client_id: 'YOUR_CLIENT_ID'})
};

fetch('https://api.simkl.com/oauth2/token', 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, "grant_type=authorization_code&client_id=YOUR_CLIENT_ID")
val request = Request.Builder()
  .url("https://api.simkl.com/oauth2/token")
  .post(body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build()

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

import Foundation

let parameters = [
  "grant_type": "authorization_code",
  "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/token")!
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))

HttpResponse<String> response = Unirest.post("https://api.simkl.com/oauth2/token")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("grant_type=authorization_code&client_id=YOUR_CLIENT_ID")
  .asString();

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

const url = 'https://api.simkl.com/oauth2/token';
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/token"

	payload := strings.NewReader("grant_type=authorization_code&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/token");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("grant_type", "authorization_code");
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/token");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddParameter("grant_type", "authorization_code");
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/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=authorization_code&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/token")

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 = "grant_type=authorization_code&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/token' -Method POST -Headers $headers -ContentType 'application/x-www-form-urlencoded' -Body 'grant_type=authorization_code&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/token");

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, "grant_type=authorization_code&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/token");

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, "grant_type=authorization_code&client_id=YOUR_CLIENT_ID");

CURLcode ret = curl_easy_perform(hnd);

{
  "access_token": "simkl_at_EXAMPLEACCESSTOKENVALUE00000000000",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "simkl_rt_EXAMPLEREFRESHTOKENVALUE0000000000",
  "scope": "media:read media:write"
}

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid, expired, or already used"
}

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Body

Parameters for POST /oauth2/token. Which ones apply depends on grant_type; every value must be a plain string.

grant_type

enum<string>

required

Selects the grant.

Available options:

authorization_code,

refresh_token,

urn:ietf:params:oauth:grant-type:device_code

client_id

string

required

Your app's client ID.

client_secret

string

Apps registered as Server apps & services only. Only needed if you are not using Authorization: Basic. Never ship this inside an app users install.

code

string

authorization_code grant. Single-use, and consumed even by a failed exchange.

code_verifier

string

authorization_code grant. 43 to 128 characters from A-Z a-z 0-9 - . _ ~. A malformed verifier is reported as invalid_grant, the same error as a genuine mismatch.

redirect_uri

string

authorization_code grant. Must match the one used to obtain the code.

refresh_token

string

refresh_token grant.

device_code

string

Device grant. From POST /oauth2/device.

scope

string

refresh_token grant only, and rarely useful: a narrower scope is ignored and a wider one is rejected.

Response

Tokens issued.

RFC 6749 section 5.1 token response. Identical in shape for all three grants.

access_token

string

required

Bearer token, 43 characters, prefixed simkl_at_. Send as Authorization: Bearer ... on every request.

token_type

enum<string>

required

Always the capitalised string Bearer. AUTH V1 returns lowercase bearer, so compare case-insensitively if you support both.

Available options:

Bearer

expires_in

integer

required

Seconds until the access token expires. Always 604800, i.e. 7 days.

Example:

604800

refresh_token

string

required

43 characters, prefixed simkl_rt_. Valid for 180 days, and the window slides forward each time you use it. Non-rotating: the same string is returned every refresh, so store it once.

scope

enum<string>

required

The scope actually granted. Always exactly one of these two values, whatever you asked for. Check it rather than assuming your request was honoured.

Available options:

media:read,

media:read media:write

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Token (V2)

Client authentication

Body format

Authorization code grant

Refresh token grant

Device code grant

Body

Response