Authorize (V2)
Browser-facing consent page for the AUTH V2 authorization code flow. This is not an API call — open it in the user’s browser (or a system web view) and let Simkl redirect back to you.
This page is on simkl.com. Pointing it at api.simkl.com returns a 404, which is the single most common mistake when wiring up OAuth.
You do not have to hardcode that host. Simkl publishes an RFC 8414 discovery document at /.well-known/oauth-authorization-server, and its authorization_endpoint always names the right one. Point a compatible library at the issuer https://simkl.com and it resolves this URL, the token URL and the supported PKCE methods for itself. See Discovery.
PKCE is mandatory: code_challenge is required and code_challenge_method must be S256. See PKCE in AUTH V2.
What comes back
On approval Simkl redirects to your redirect_uri with code, your state echoed byte-for-byte, and iss (RFC 9207). On refusal it redirects with error=access_denied instead.
Errors split by whether the redirect target can be trusted. A bad client_id or an unregistered redirect_uri renders a JSON error and never redirects, which prevents your app being used as an open redirect. Everything else redirects back with error set.
redirect_uri is validated before PKCE, so while the redirect URI is wrong you will not be told that your PKCE parameters are also missing.
After approval Simkl may show a brief interstitial before redirecting. That is deliberate and gives the authorization code time to replicate between regions.
Query Parameters
Your app's client ID. Must be registered for OAuth V2.
Must match a URI registered on your app. Matching is exact, with two relaxations: loopback hosts (127.0.0.1, ::1, localhost) ignore the port, and apps registered as Mobile, desktop & browser apps may use a registered *.local host if the ports match. A fragment is always rejected. A registered https://app/cb does not match a requested https://app/cb?x=1 -- query strings only work via exact match.
Always code. Required by RFC 6749 section 4.1.1 and sent automatically by every conformant OAuth library. Simkl does not currently reject a request that omits it, but send it anyway -- it is the only value the authorization endpoint supports, and relying on the omission being tolerated is not something to build on.
code base64url SHA-256 of your code_verifier, no padding.
Must be S256. plain is rejected.
S256 Space-separated scopes. Omitting this grants media:read only, so an app that writes must ask for media:write explicitly. An unrecognised scope string is silently treated as read-only rather than rejected, so a typo costs you write access with no error. Always check the scope in the token response.
media:read, media:read media:write Opaque CSRF value, echoed back byte-for-byte. Generate one per flow, store it, and reject the callback if it does not match.
Response
Redirect to your redirect_uri, carrying either code (plus state and iss) or error.