OAuth client libraries

Fastest path — skip the OAuth library entirely. Simkl’s OAuth flow is two HTTP steps:

Redirect the user to https://simkl.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=... — they approve in the browser, Simkl bounces back to your redirect_uri with ?code=...&state=... in the query string.
POST that code to https://api.simkl.com/oauth/token with client_id, client_secret, redirect_uri, and grant_type=authorization_code in the body — the response is {"access_token": "...", "token_type": "bearer", "scope": "public", "expires_in": 157680000}. Send that token as Authorization: Bearer ... on every authenticated request.

That’s it. No refresh-token rotation, no scope dance — Simkl tokens are long-lived (expires_in is 5 years) and only invalidate when the user revokes from Connected Apps. For the full walkthroughs, see OAuth 2.0 flow (server-side with client_secret) or PKCE flow (mobile / SPA / desktop without client_secret).

Simkl’s POST /oauth/token accepts both application/x-www-form-urlencoded (the RFC 6749 §3.2 default) and application/json, and reads client credentials from either the request body or an Authorization: Basic header (RFC 6749 §2.3.1). Discovery metadata is at https://simkl.com/.well-known/oauth-authorization-server (RFC 8414) — modern libraries can auto-configure from it.

Quick library status

Every library below was driven through the full browser-consent → real authorize code → real token mint flow against api.simkl.com. Each one returned a real access_token we then used to call /users/settings successfully.

Language	Library	Default config status
Python	authlib	✅ Works as-is
Python	requests-oauthlib	✅ Works as-is
Python	httpx-oauth	✅ Works as-is
Node.js	openid-client v6 (panva)	✅ Works — pass `{algorithm: 'oauth2'}` to `discovery()`
Node.js	oauth4webapi (panva)	✅ Works — pass `{algorithm: 'oauth2'}` to `discoveryRequest()`
Node.js	simple-oauth2	✅ Works as-is
Node.js	passport-oauth2	✅ Works as-is
Node.js	@badgateway/oauth2-client	✅ Works as-is
Java	Nimbus OAuth 2.0 SDK	✅ Works as-is
Java	Spring Security OAuth2 Client	✅ Works as-is
Java	Google OAuth Client for Java	✅ Works as-is
Java	scribejava-core	✅ Works as-is
Go	golang.org/x/oauth2	✅ Works as-is
PHP	league/oauth2-client	✅ Works as-is
Any	raw HTTP (curl, fetch, requests, …)	✅ Reference path

Most libraries need no configuration beyond the two endpoint URLs and your credentials. The only outliers are openid-client v6 and oauth4webapi — both default to OIDC discovery (/.well-known/openid-configuration), but Simkl is OAuth2-only, so they need an explicit { algorithm: 'oauth2' } option to use our RFC 8414 metadata endpoint. One-line fix shown in their snippets.

The wire format

curl -X POST https://api.simkl.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "User-Agent: my-app-name/1.0" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=YOUR_REDIRECT_URI" \
  --data-urlencode "grant_type=authorization_code"

Success response:

{
  "access_token": "<64-hex-char bearer token>",
  "token_type":   "bearer",
  "scope":        "public",
  "expires_in":   157680000
}

The PKCE variant swaps client_secret for code_verifier.

Python authlib

# pip install authlib httpx
from authlib.integrations.httpx_client import OAuth2Client

client = OAuth2Client("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET",
                      token_endpoint="https://api.simkl.com/oauth/token")
token = client.fetch_token(
    "https://api.simkl.com/oauth/token",
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    redirect_uri="YOUR_REDIRECT_URI",
)
print(token["access_token"])

Python requests-oauthlib

# pip install requests-oauthlib
from requests_oauthlib import OAuth2Session

session = OAuth2Session("YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI")
token = session.fetch_token(
    "https://api.simkl.com/oauth/token",
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    client_secret="YOUR_CLIENT_SECRET",
)
print(token["access_token"])

Python httpx-oauth

# pip install httpx-oauth
import asyncio
from httpx_oauth.oauth2 import BaseOAuth2

client = BaseOAuth2(
    "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET",
    authorize_endpoint="https://simkl.com/oauth/authorize",
    access_token_endpoint="https://api.simkl.com/oauth/token",
)
token = asyncio.run(client.get_access_token(
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    redirect_uri="YOUR_REDIRECT_URI",
))
print(token["access_token"])

Node openid-client v6

// npm install openid-client
import * as client from "openid-client";

// {algorithm: 'oauth2'} → use /.well-known/oauth-authorization-server (RFC 8414).
// Default would call /.well-known/openid-configuration which Simkl is not.
const config = await client.discovery(
  new URL("https://simkl.com"),
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
  undefined,
  { algorithm: "oauth2" },
);

const callback = new URL("YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE");
const token = await client.authorizationCodeGrant(config, callback);
console.log(token.access_token);

Node oauth4webapi

// npm install oauth4webapi
import * as oauth from "oauth4webapi";

const issuer = new URL("https://simkl.com");
// {algorithm: 'oauth2'} → use RFC 8414 metadata, not OIDC.
const discoveryResp = await oauth.discoveryRequest(issuer, { algorithm: "oauth2" });
const as = await oauth.processDiscoveryResponse(issuer, discoveryResp);

const clientObj = { client_id: "YOUR_CLIENT_ID" };
const clientAuth = oauth.ClientSecretBasic("YOUR_CLIENT_SECRET");

const callbackUrl = new URL("YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE");
const params = oauth.validateAuthResponse(as, clientObj, callbackUrl, "YOUR_STATE");
const response = await oauth.authorizationCodeGrantRequest(
  as, clientObj, clientAuth, params, "YOUR_REDIRECT_URI", oauth.nopkce,
);
const token = await response.json();
console.log(token.access_token);

Node simple-oauth2

// npm install simple-oauth2
import { AuthorizationCode } from "simple-oauth2";

const oauth = new AuthorizationCode({
  client: { id: "YOUR_CLIENT_ID", secret: "YOUR_CLIENT_SECRET" },
  auth:   { tokenHost: "https://api.simkl.com", tokenPath: "/oauth/token" },
});

const result = await oauth.getToken({
  code: "AUTHORIZATION_CODE_FROM_REDIRECT",
  redirect_uri: "YOUR_REDIRECT_URI",
});
console.log(result.token.access_token);

Node passport-oauth2

// npm install passport-oauth2
import OAuth2Strategy from "passport-oauth2";

passport.use(new OAuth2Strategy(
  {
    authorizationURL: "https://simkl.com/oauth/authorize",
    tokenURL:         "https://api.simkl.com/oauth/token",
    clientID:         "YOUR_CLIENT_ID",
    clientSecret:     "YOUR_CLIENT_SECRET",
    callbackURL:      "YOUR_REDIRECT_URI",
  },
  (accessToken, refreshToken, profile, done) => done(null, { accessToken }),
));

Node @badgateway/oauth2-client

// npm install @badgateway/oauth2-client
import { OAuth2Client } from "@badgateway/oauth2-client";

const client = new OAuth2Client({
  clientId:              "YOUR_CLIENT_ID",
  clientSecret:          "YOUR_CLIENT_SECRET",
  tokenEndpoint:         "https://api.simkl.com/oauth/token",
  authorizationEndpoint: "https://simkl.com/oauth/authorize",
});

const token = await client.authorizationCode.getTokenFromCodeRedirect(
  "YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE",
  { redirectUri: "YOUR_REDIRECT_URI" },
);
console.log(token.accessToken);

Java Nimbus OAuth 2.0 SDK

// Maven: com.nimbusds:oauth2-oidc-sdk:11.21
import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.auth.*;
import com.nimbusds.oauth2.sdk.id.ClientID;
import java.net.URI;

TokenRequest req = new TokenRequest(
    new URI("https://api.simkl.com/oauth/token"),
    new ClientSecretBasic(new ClientID("YOUR_CLIENT_ID"), new Secret("YOUR_CLIENT_SECRET")),
    new AuthorizationCodeGrant(
        new AuthorizationCode("AUTHORIZATION_CODE_FROM_REDIRECT"),
        new URI("YOUR_REDIRECT_URI")
    )
);
AccessTokenResponse tok = TokenResponse.parse(req.toHTTPRequest().send()).toSuccessResponse();
System.out.println(tok.getTokens().getAccessToken().getValue());

Java Spring Security OAuth2 Client

# application.yml — discovery auto-configures the rest.
spring:
  security:
    oauth2:
      client:
        registration:
          simkl:
            client-id:                YOUR_CLIENT_ID
            client-secret:            YOUR_CLIENT_SECRET
            authorization-grant-type: authorization_code
            redirect-uri:             "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          simkl:
            issuer-uri: https://simkl.com

Spring fetches /.well-known/oauth-authorization-server from the issuer-uri and wires up authorization_endpoint + token_endpoint automatically. Default client_secret_basic works.

Java Google OAuth Client for Java

// Maven: com.google.oauth-client:google-oauth-client:1.38.0 + google-http-client-jackson2:1.45.3
import com.google.api.client.auth.oauth2.AuthorizationCodeTokenRequest;
import com.google.api.client.http.BasicAuthentication;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;

var req = new AuthorizationCodeTokenRequest(
    new NetHttpTransport(), JacksonFactory.getDefaultInstance(),
    new GenericUrl("https://api.simkl.com/oauth/token"),
    "AUTHORIZATION_CODE_FROM_REDIRECT");
req.setRedirectUri("YOUR_REDIRECT_URI");
req.setClientAuthentication(new BasicAuthentication("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET"));
System.out.println(req.execute().getAccessToken());

Java scribejava-core

// Maven: com.github.scribejava:scribejava-core:8.3.3 + scribejava-java8:8.3.3
import com.github.scribejava.core.builder.ServiceBuilder;
import com.github.scribejava.core.builder.api.DefaultApi20;
import com.github.scribejava.core.oauth2.clientauthentication.*;

class SimklApi extends DefaultApi20 {
  public String getAccessTokenEndpoint()     { return "https://api.simkl.com/oauth/token"; }
  protected String getAuthorizationBaseUrl() { return "https://simkl.com/oauth/authorize"; }
  @Override public ClientAuthentication getClientAuthentication() {
    return HttpBasicAuthenticationScheme.instance();
  }
}

var service = new ServiceBuilder("YOUR_CLIENT_ID")
    .apiSecret("YOUR_CLIENT_SECRET")
    .callback("YOUR_REDIRECT_URI")
    .build(new SimklApi());
var token = service.getAccessToken("AUTHORIZATION_CODE_FROM_REDIRECT");
System.out.println(token.getAccessToken());

Go golang.org/x/oauth2

// go get golang.org/x/oauth2
import (
    "context"
    "golang.org/x/oauth2"
)

cfg := &oauth2.Config{
    ClientID:     "YOUR_CLIENT_ID",
    ClientSecret: "YOUR_CLIENT_SECRET",
    RedirectURL:  "YOUR_REDIRECT_URI",
    Endpoint: oauth2.Endpoint{
        AuthURL:  "https://simkl.com/oauth/authorize",
        TokenURL: "https://api.simkl.com/oauth/token",
    },
}
tok, _ := cfg.Exchange(context.Background(), "AUTHORIZATION_CODE_FROM_REDIRECT")
fmt.Println(tok.AccessToken)

PHP league/oauth2-client

// composer require league/oauth2-client
require __DIR__ . "/vendor/autoload.php";

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    "clientId"                => "YOUR_CLIENT_ID",
    "clientSecret"            => "YOUR_CLIENT_SECRET",
    "redirectUri"             => "YOUR_REDIRECT_URI",
    "urlAuthorize"            => "https://simkl.com/oauth/authorize",
    "urlAccessToken"          => "https://api.simkl.com/oauth/token",
    "urlResourceOwnerDetails" => "https://api.simkl.com/users/settings",
]);
$token = $provider->getAccessToken("authorization_code", ["code" => "AUTHORIZATION_CODE_FROM_REDIRECT"]);
echo $token->getToken();

Raw HTTP

curl -X POST https://api.simkl.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "User-Agent: my-app-name/1.0" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "code=AUTHORIZATION_CODE_FROM_REDIRECT" \
  --data-urlencode "redirect_uri=YOUR_REDIRECT_URI" \
  --data-urlencode "grant_type=authorization_code"

Other OAuth libraries (inferred from RFC compliance)

These libraries aren’t in our live test harness, so the status below is read from each library’s source/docs — not from a captured request to api.simkl.com. Most wrap one of the live-tested libraries above; the rest follow the same RFC defaults Simkl now accepts.

Language	Library	Inferred
Python	Django allauth, python-social-auth, fastapi-users	Wraps `requests-oauthlib` — should work as-is.
Node.js	NextAuth.js / Auth.js, express-openid-connect	Wraps `openid-client` — works with `{algorithm: 'oauth2'}` discovery.
Node.js	grant (server middleware), oidc-client-ts	Default RFC config matches Simkl.
.NET	Duende.IdentityModel, OpenIddict (client), MS.AspNetCore.Authentication.OpenIdConnect	Default Basic Auth / discovery flows align with Simkl.
.NET	Microsoft.Identity.Client (MSAL)	Auth-code grant should work; broker / conditional access flows out of scope.
Server-side PHP	HWIOAuthBundle (Symfony)	Wraps `league/oauth2-client` — should work as-is.
Ruby	oauth2 gem, omniauth-oauth2	Default `auth_scheme: :basic_auth` accepted.
Rust	oauth2 crate, openidconnect crate (ramosbugs)	Default `AuthType::BasicAuth` accepted.
Mobile	AppAuth-iOS / AppAuth-Android / AppAuth-JS / react-native-app-auth	RFC default — should work as-is.
Postman	Built-in OAuth 2.0 helper	Both “Send as Basic Auth header” and “Send client credentials in body” modes accepted.
OpenAPI Generator	Generated clients (all languages)	Generators emit RFC-conformant clients.

If you hit a library not on this list, the sanity check is one HTTP capture: confirm the token POST hits https://api.simkl.com/oauth/token, sends client_id / code / redirect_uri / grant_type (and client_secret either in the body or in Authorization: Basic), and see what comes back. If the request looks RFC-shaped and you still hit an error, let us know — we’d appreciate the capture so we can promote the library to the live matrix.

OAuth 2.0 walkthrough

Confidential (server-side) flow.

Public PKCE walkthrough

Mobile / SPA / desktop flow without client_secret.

PIN flow

TV / console / CLI flow with a 5-character code.

​Quick library status

​The wire format

​Python authlib

​Python requests-oauthlib

​Python httpx-oauth

​Node openid-client v6

​Node oauth4webapi

​Node simple-oauth2

​Node passport-oauth2

​Node @badgateway/oauth2-client

​Java Nimbus OAuth 2.0 SDK

​Java Spring Security OAuth2 Client

​Java Google OAuth Client for Java

​Java scribejava-core

​Go golang.org/x/oauth2

​PHP league/oauth2-client

​Raw HTTP

​Other OAuth libraries (inferred from RFC compliance)

​See also