Skip to main content
GET
/
oauth
/
pin
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>'
{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://api.simkl.org/llms.txt

Use this file to discover all available pages before exploring further.

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

OK

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