Guide

SuperTokens, open core et modules complémentaires payants

SuperTokens sépare cœur, SDK backend et SDK frontend. Licence Apache 2.0 mais répertoire ee propriétaire, fonctionnalités payantes, prix et alternatives.

L'équipe CodeWorlds19 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

SuperTokens résout l'authentification avec une architecture en trois parties : un service séparé appelé le cœur, une bibliothèque dans votre backend et une bibliothèque dans votre frontend. Le cœur est sous licence Apache 2.0, mais le répertoire ee du même dépôt porte une licence propriétaire, et plusieurs fonctionnalités dont on a assez vite besoin se trouvent justement là.

Trois pièces mobiles au lieu d'une bibliothèque

Le cœur est un programme Java qui écoute par défaut sur le port 3567. Il conserve les utilisateurs, les mots de passe, les sessions et les rôles dans une base de données qu'il migre lui-même au démarrage. Depuis la version 11.0.0, seul PostgreSQL en version 13.0 ou plus récente est pris en charge ; MySQL et MongoDB ont été retirés, donc si vous vous souvenez d'anciennes entrées de la documentation, elles ne s'appliquent plus. On en apprend davantage sur la base de données elle-même dans l'article PostgreSQL.

La deuxième pièce est le SDK backend. Pour Node, c'est le paquet supertokens-node, qui expose un ensemble de routes sous un préfixe commun à l'intérieur de votre application et dialogue avec le cœur en HTTP. Chaque requête vers le cœur porte un en-tête cdi-version et, si le cœur a des api_keys configurées, un en-tête api-key. La troisième pièce est le SDK frontend : supertokens-auth-react avec des composants de connexion prêts à l'emploi, ou supertokens-web-js si vous écrivez l'interface vous-même.

La documentation de déploiement qualifie le cœur de composant backend de confiance et recommande expressément de le garder sur un réseau privé accessible uniquement par votre backend, jamais par le navigateur. Ce n'est pas un conseil décoratif : un cœur sans clé d'API permet à quiconque peut l'atteindre de lister et de modifier les utilisateurs.

Le coût de maintenance de cet agencement mérite un décompte honnête. C'est un conteneur de plus dans votre infrastructure, une base de données de plus ou un schéma de plus dans une base existante, des migrations lancées par le cœur à chaque démarrage et trois endroits où les versions doivent concorder. Une bibliothèque qui vit dans le même processus que votre application, comme Better Auth, n'a pas du tout ce problème.

Versions, licence et contenu des paquets publiés

J'ai vérifié la licence sous trois angles, car la déclaration dans un registre de paquets ne suffit pas.

Dans le registre npm, le paquet supertokens-node est en version 24.0.3 publiée le 24 juillet 2026, avec le champ license à Apache-2.0. supertokens-auth-react est en 0.51.3 du 30 juillet 2026, supertokens-web-js en 0.16.0 du 15 août 2025 et supertokens-website en 20.1.6 du 21 mars 2025, tous avec le même champ de licence. Sur PyPI, supertokens-python est en 0.31.3 du 6 mai 2026 et déclare Apache 2.0 avec le classifieur OSI.

Dans le dépôt, le fichier de licence s'appelle LICENSE.md, pas LICENSE, et récupérer ce dernier nom renvoie une 404. Son contenu est plus intéressant qu'un simple texte Apache, car il s'ouvre sur une séparation : tout ce qui se trouve sous le répertoire ee/ relève d'un fichier distinct, ee/LICENSE.md, et le reste est sous Apache 2.0. Ce fichier distinct est la SuperTokens Enterprise License. Elle indique clairement que le logiciel du répertoire ee ne peut être utilisé en production qu'avec un abonnement valide pour le bon nombre de postes, que la copie et la modification pour le développement et les tests sont permises sans abonnement, et que la copie, la publication, la distribution et la vente sont interdites. C'est une licence propriétaire, pas une licence ouverte, et elle se trouve dans le même arbre de sources que tout le reste.

La troisième source est le contenu des paquets publiés, car c'est là que d'autres projets réservent le plus souvent des surprises. L'archive supertokens-node-24.0.3.tgz pèse environ 554 ko, contient 1015 entrées dont 397 fichiers .js, plus un fichier package/LICENSE.md avec un en-tête Apache 2.0 et une mention de copyright de VRAI Labs de 2021. L'archive supertokens-auth-react en 0.51.3 porte aussi package/LICENSE.md avec la même mention, datée de 2020, et 82 fichiers .js. Autrement dit : les deux paquets contiennent du vrai code et un vrai fichier de licence, les déclarations concordent et il n'y a pas de coquille vide ici.

Le projet est actif d'une façon qui se voit dans le flux des versions. J'ai vérifié les dates une par une, car c'est facile de se tromper : l'entrée v12.1.1 est datée du 13 août 2026 et v12.1.0 du 12 août, un jour plus tôt et non le même jour. Le 6 août 2026, en revanche, quatre versions sont arrivées d'un coup, v12.0.10, v12.0.9, v11.4.7 et v11.3.7, réparties sur un peu moins de sept heures. Maintenir plusieurs lignes à la fois et reporter les correctifs sur d'anciennes branches est un bon signal pour qui ne veut pas mettre à jour le cœur chaque mois.

Un détail de dépendances mérite d'être mentionné : supertokens-node 24.0.3 tire quinze paquets, dont twilio en ^4.19.3 et nodemailer en ^8.0.2. Ils atterrissent dans node_modules que vous envoyiez ou non des SMS ou des e-mails par ces canaux.

Ce qui est gratuit et ce qui exige une licence payante

C'est le cœur du sujet et la surprise la plus courante pendant un déploiement. La liste des fonctionnalités couvertes par la licence commerciale n'est pas une question d'interprétation, car elle figure dans le code source du cœur comme l'énumération EE_FEATURES. Dans la version v12.1.1, elle contient les valeurs account_linking, multi_tenancy, test, dashboard_login, mfa, security, oauth et saml.

Fonctionnalité dans EE_FEATURESCe que c'estPrix sur la page des tarifs
mfaauthentification multifacteur, TOTP, OTP, passkeys0,01 USD par MAU, minimum 100 USD par mois
account_linkinglier les comptes d'un même utilisateur0,005 USD par MAU, minimum 100 USD par mois
dashboard_logintableau de bord d'administration au-delà de trois comptes20 USD par compte et par mois
multi_tenancymulti-tenance et prise en charge des organisationsaucun chiffre, un lien « See pricing »
oauthvotre application dans le rôle de fournisseur OAuth 2.0aucun chiffre, « Contact us »
samlconnexion SAMLaucun chiffre, absent de la liste des options
securityAttack Protection Suiteaucun chiffre, « Contact us »

Beaucoup de choses restent du côté gratuit, et c'est la partie équitable de l'arrangement. Connexion par mot de passe, connexion sociale et fournisseurs OpenID personnalisés arbitraires, connexion sans mot de passe par lien magique et par code à usage unique par e-mail ou SMS, vérification d'adresse, réinitialisation du mot de passe, gestion de session par cookies, rôles et permissions, interface de connexion préconstruite et mécanisme de surcharge du SDK. Le tableau de bord d'administration est gratuit aussi, mais pour trois comptes : la constante MAX_NUMBER_OF_FREE_DASHBOARD_USERS de la classe Dashboard vaut 3, et ajouter un quatrième compte sans clé lève une FeatureNotEnabledException.

Deux choses sont gênantes dans ce tableau. D'abord, saml figure dans l'énumération des fonctionnalités payantes, mais la page des tarifs ne le liste jamais parmi les options tarifées, alors que le tableau comparatif avec la concurrence affiche « SAML Login: Yes ». Vous ne pouvez pas lire dans la documentation du fournisseur ce que cela coûte. Ensuite, le code source du cœur contient un tableau ENTERPRISE_THIRD_PARTY_IDS avec les valeurs google-workspaces, okta, active-directory et boxy-saml, utilisé pour compter les statistiques d'usage des fonctionnalités payantes. Si vous prévoyez une connexion d'entreprise via Okta ou Active Directory, c'est exactement le domaine où la facturation cesse d'être gratuite.

La documentation des fonctionnalités payantes les signale par un encadré « This feature is only available to paid users » et un bouton « View Details ». Le contenu derrière ce bouton ne s'affiche que dans un navigateur, donc récupérer la page avec un outil en ligne de commande ne montre aucun prix. Si vous voulez des chiffres, il faut ouvrir la page des tarifs.

La clé de licence en pratique

La clé est transmise au cœur par l'API /ee/license. Un PUT avec un champ licenseKey dans le corps enregistre la clé et synchronise immédiatement la liste des fonctionnalités, GET renvoie la clé actuellement configurée et DELETE la supprime. L'appel est limité à une application et ne peut être fait que depuis le tenant public.

Bash
# set the licence key on the core
curl -X PUT http://127.0.0.1:3567/ee/license \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_CORE_API_KEY' \
  -d '{"licenseKey":"..."}'

# check what the core has stored
curl -X GET http://127.0.0.1:3567/ee/license \
  -H 'api-key: YOUR_CORE_API_KEY'

# remove the key and fall back to the open features
curl -X DELETE http://127.0.0.1:3567/ee/license \
  -H 'api-key: YOUR_CORE_API_KEY'

La vérification de la clé suit l'un de deux chemins, et la différence compte pour un déploiement isolé du réseau. La méthode doesLicenseKeyRequireServerQuery vérifie simplement si la clé découpée sur les points a trois parties. Si c'est le cas, c'est un JWT et le cœur le vérifie localement avec une clé publique RSA compilée dans le code source. Sinon, le cœur envoie une requête POST à https://api.supertokens.com/0/st/license/check.

Le contenu de cette requête est visible dans le code : telemetryId, licenseKey, superTokensVersion et un objet paidFeatureUsageStats. Le dernier porte des compteurs d'usage, par exemple user_count pour le tableau de bord d'administration et des statistiques pour la MFA, la multi-tenance et la liaison de comptes. La constante INTERVAL_BETWEEN_SERVER_SYNC vaut 3600 * 24 secondes, donc la synchronisation se répète une fois par jour, et INTERVAL_BETWEEN_DB_READS est de quatre heures, après quoi le cœur relit l'état enregistré des indicateurs. Le résultat atterrit dans la base de données sous les clés LICENSE_KEY et FEATURE_FLAG.

La conclusion pratique : l'auto-hébergement ne signifie pas automatiquement que le cœur reste muet. Avec une clé au format JWT, c'est le cas. Avec une clé qui ne ressemble pas à un JWT, il contacte le serveur une fois par jour et envoie des statistiques d'usage avec un identifiant de télémétrie. Si vous travaillez sur un réseau sans route vers l'extérieur, c'est une question à poser au fournisseur avant de signer, pas après.

Tarifs et arithmétique

La page des tarifs distingue deux variantes. Dans le cloud, vous payez 0,02 USD par utilisateur actif mensuel, et en dessous de cinq mille utilisateurs de ce type c'est gratuit. La variante auto-hébergée est décrite comme gratuite et open source sans limite d'utilisateurs, ce qui ne vaut que pour les fonctionnalités ouvertes.

ÉlémentCloudAuto-hébergé
Base0,02 USD par MAU, gratuit en dessous de 5000 MAUgratuit, aucune limite de MAU
MFA0,01 USD par MAU, minimum 100 USD par moismême tarif et même minimum
Liaison de comptes0,005 USD par MAU, minimum 100 USD par moismême tarif et même minimum
Comptes du tableau de bord20 USD par compte, les trois premiers gratuitsmême tarif
Multi-tenanceaucun chiffre donnéaucun chiffre donné

J'ai vérifié l'arithmétique des exemples de la page et elle tient. Pour 5000 utilisateurs avec la liaison de comptes activée, cela fait (0.02 + 0.005) * 5000 = 125 USD par mois, et pour 7000 utilisateurs (0.02 + 0.005) * 7000 = 175 USD. Les 100 USD par mois annoncés pour la plage de 1 à 4999 utilisateurs tiennent aussi, car le minimum de facturation des options s'y applique.

Attention au seuil gratuit : c'est une falaise, pas une déduction. À 4999 utilisateurs, la base cloud coûte zéro, à 5000 vous payez 0,02 USD pour les cinq mille, soit 100 USD, et c'est précisément ainsi que l'exemple du fournisseur le calcule. Le deuxième point est le minimum mensuel de 100 USD sur la MFA et sur la liaison de comptes. Cela signifie que le scénario de MFA le moins cher sur votre propre serveur, avec cinquante utilisateurs, coûte 100 USD par mois, soit 1200 USD par an. Cela surprend les gens qui ont choisi SuperTokens précisément pour éviter de payer par MAU.

Il y a aussi un écart à l'intérieur de la page elle-même. Le calculateur a une ligne « Multitenancy » qui affiche 0 USD dans les deux colonnes, alors que la liste des fonctionnalités payantes vous renvoie à « See pricing » pour la multi-tenance sans chiffre. La multi-tenance figure dans EE_FEATURES, donc elle ne fonctionnera pas sans clé, mais aucun prix ne peut être lu dans la documentation du fournisseur. La section des questions de la page des tarifs ajoute qu'au-dessus de dix mille utilisateurs actifs mensuels, ou de plus de cinq organisations comme clients, une remise peut être négociée, là encore sans donner de tarifs.

Le lancer de zéro

Le cœur se monte le plus facilement depuis une image de conteneur. La documentation nomme l'image supertokens/supertokens-postgresql, tandis que le README du projet de l'image renvoie à registry.supertokens.io/supertokens/supertokens-postgresql.

Bash
# core with your own PostgreSQL database
docker run -p 3567:3567 -d \
  -e POSTGRESQL_CONNECTION_URI="postgresql://user:pass@db:5432/supertokens" \
  -e API_KEYS="long-random-string" \
  registry.supertokens.io/supertokens/supertokens-postgresql

# check that the core came up
curl http://127.0.0.1:3567/hello

Sans les variables POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_PASSWORD_FILE et POSTGRESQL_CONNECTION_URI, le cœur démarre sur une base de données en mémoire. La démo fonctionne, la connexion fonctionne, et après un redémarrage du conteneur il ne reste pas un seul utilisateur. Le même README ajoute qu'au démarrage le cœur attend jusqu'à environ une heure que PostgreSQL devienne disponible, donc un conteneur qui paraît bloqué attend peut-être simplement la base de données.

La configuration peut aussi venir d'un fichier. À l'intérieur du conteneur, il se trouve à /usr/lib/supertokens/config.yaml et accepte des champs comme ceux-ci :

YAML
# fragment of the core config.yaml
port: 3567
host: "0.0.0.0"
api_keys: "long-random-string"
access_token_validity: 3600          # seconds
refresh_token_validity: 144000       # minutes, not seconds
password_hashing_alg: "BCRYPT"       # or "ARGON2"
bcrypt_log_rounds: 11
ip_allow_regex: "10\\.0\\..*"
log_level: "INFO"
disable_telemetry: true

Le backend s'initialise une fois, au démarrage de l'application. Le type TypeInput de supertokens-node accepte les champs supertokens, framework, appInfo, recipeList, telemetry, isInServerlessEnv et debug. Le champ framework accepte les valeurs express, fastify, hapi, loopback, koa, awsLambda et custom.

TypeScript
import supertokens from "supertokens-node"
import Session from "supertokens-node/recipe/session"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import Dashboard from "supertokens-node/recipe/dashboard"

supertokens.init({
  framework: "express",
  supertokens: {
    connectionURI: process.env.SUPERTOKENS_CONNECTION_URI!,
    apiKey: process.env.SUPERTOKENS_API_KEY
  },
  appInfo: {
    appName: "code-worlds",
    apiDomain: "https://api.example.com",
    websiteDomain: "https://example.com",
    apiBasePath: "/auth",
    websiteBasePath: "/auth"
  },
  recipeList: [EmailPassword.init(), Session.init(), Dashboard.init()],
  telemetry: false
})

Le frontend reçoit un objet appInfo presque identique, ce qui est pratique, car les deux côtés doivent s'accorder sur les préfixes de routes. Si vous construisez sur Next.js, rappelez-vous que apiDomain et websiteDomain seront la même adresse.

TypeScript
import SuperTokens from "supertokens-auth-react"
import Session from "supertokens-auth-react/recipe/session"
import EmailPassword from "supertokens-auth-react/recipe/emailpassword"

SuperTokens.init({
  appInfo: {
    appName: "code-worlds",
    apiDomain: "https://api.example.com",
    websiteDomain: "https://example.com",
    apiBasePath: "/auth",
    websiteBasePath: "/auth"
  },
  recipeList: [EmailPassword.init(), Session.init()]
})

La compatibilité de versions entre le cœur et les SDK est un vrai piège lors des mises à niveau, car vous mettez à jour trois choses et les trois doivent concorder. Le fournisseur publie un tableau de compatibilité à /docs/references/compatibility-table, mais ses listes de versions ne se chargent que dans un navigateur. La page récupérée sans exécuter JavaScript n'affiche que les titres, « Compatible Backend SDK Versions », « SuperTokens Core Version » et « Compatible Frontend SDK Versions », sans un seul nombre. Le tableau existe, mais un script dans un pipeline d'intégration continue ne peut pas le vérifier. Le mécanisme sous-jacent est une négociation d'interface : les requêtes portent un en-tête cdi-version, et la configuration du cœur a des champs supertokens_max_cdi_version et supertokens_min_cdi_version.

SuperTokens face aux alternatives

OutilModèleOù vivent les données utilisateurCe que vous payez
SuperTokensopen core, un service séparé plus deux SDKchez vous ou dans le cloud du fournisseur0,02 USD par MAU dans le cloud, options payantes même en auto-hébergé
Better Authune bibliothèque dans votre processus, version 1.7.1 sous MITtoujours chez vousrien pour la bibliothèque elle-même
Clerkservice ferméchez le fournisseurpar utilisateur actif
Auth0service ferméchez le fournisseurpar utilisateur actif et par fonctionnalité
WorkOSservice ferméchez le fournisseurpar connexion à un fournisseur d'identité

La place qu'occupe SuperTokens sur cette carte est assez précise. Si l'exigence principale est que la base d'utilisateurs et les hachages de mots de passe ne quittent jamais votre infrastructure, tout en ne voulant pas écrire de zéro les flux de réinitialisation de mot de passe et de rotation de session, c'est un bon choix. Si tout ce qui compte pour vous est de ne pas payer, Better Auth obtient le même effet sans conteneur supplémentaire et sans catégorie de fonctionnalités payantes. Si en revanche vous valorisez le temps de votre équipe au-dessus de la facture, des services gérés comme Clerk, Auth0 ou Kinde vous épargnent toute la couche opérationnelle, au prix de la remise des données et de la dépendance à un fournisseur. Un cas à part est la vente à de grandes entreprises, où le nombre de fournisseurs d'identité connectés domine, et là la facturation par connexion de WorkOS convient mieux.

La dépendance à un fournisseur avec SuperTokens est moindre qu'avec les services fermés, mais elle n'est pas nulle. Le schéma de la base de données est le vôtre et vous pouvez le lire, mais les mots de passe sont hachés avec l'algorithme réglé dans password_hashing_alg, et les flux de session supposent la présence du cœur. Migrer vers autre chose signifie déplacer les hachages et obliger tout le monde à se reconnecter, pas simplement remplacer une bibliothèque.

Un nom de cette catégorie demande une correction, car il circule encore dans les guides. Stack Auth, autrefois listé à côté de SuperTokens comme alternative ouverte à Clerk, s'appelle aujourd'hui Hexclave : le dépôt et le domaine redirigent vers la nouvelle marque, et les paquets @stackframe/* ont été remplacés par la famille @hexclave/*. La répartition des licences y ressemble à celle d'ici, un client MIT et des composants serveur AGPLv3, mais avec deux différences qui jouent dans le mauvais sens : le champ license manque dans les métadonnées de six paquets à la fois, et la mention de copyright porte encore l'ancien nom de l'entreprise.

Erreurs courantes

La première et la plus coûteuse : supposer que l'auto-hébergement signifie que tout est gratuit. Ce qui est ouvert, c'est le cœur en dehors du répertoire ee. La MFA, la liaison de comptes, la multi-tenance, le rôle de fournisseur OAuth 2.0, SAML et la suite de protection contre les attaques exigent tous une clé même quand vous payez vous-même l'électricité du serveur.

La deuxième : laisser la base de données en mémoire. Un conteneur sans variables POSTGRESQL_* démarre correctement et passe les tests, puis perd ses données à chaque redémarrage.

La troisième : exposer le cœur à Internet. Sans api_keys, le port 3567 donne un accès complet aux utilisateurs. Il existe aussi ip_allow_regex et ip_deny_regex, qu'il vaut la peine de régler même sur un réseau privé.

La quatrième : mettre à niveau le SDK sans le cœur, ou l'inverse. L'en-tête cdi-version rejettera une combinaison incompatible, et le tableau de compatibilité ne peut pas être vérifié par un script, donc cela doit se faire à la main avant le déploiement.

La cinquième : ajouter un quatrième compte au tableau de bord d'administration. La constante MAX_NUMBER_OF_FREE_DASHBOARD_USERS vaut 3, et le compte supplémentaire coûte 20 USD par mois.

La sixième : supposer que la vérification de la licence est locale. Une clé au format JWT est vérifiée hors ligne, toute autre clé déclenche une requête vers api.supertokens.com une fois par jour avec des statistiques d'usage.

FAQ

L'auto-hébergement de SuperTokens est-il vraiment gratuit ?

En partie. La connexion par mot de passe, la connexion sociale, la connexion sans mot de passe, la vérification d'adresse, les sessions, les rôles et permissions, et le tableau de bord jusqu'à trois comptes sont gratuits sans limite d'utilisateurs. Les fonctionnalités listées dans l'énumération EE_FEATURES exigent une clé payante quel que soit l'endroit où tourne le cœur.

Quelles fonctionnalités exigent exactement une clé de licence ?

Dans la version v12.1.1, ce sont account_linking, multi_tenancy, dashboard_login au-delà de trois comptes, mfa, security, oauth et saml. Des prix explicites ne sont donnés que pour la MFA, la liaison de comptes et les comptes du tableau de bord. Pour le reste, le fournisseur vous renvoie à un formulaire de contact.

Le cœur se connecte-t-il à Internet ?

Cela dépend du format de la clé. Une clé en trois parties est un JWT vérifié localement. Toute autre clé déclenche un appel à https://api.supertokens.com/0/st/license/check une fois par jour, avec un identifiant de télémétrie et des compteurs d'usage des fonctionnalités payantes. La télémétrie peut être désactivée séparément par disable_telemetry dans la configuration du cœur et telemetry: false dans le SDK.

Puis-je utiliser MySQL ou MongoDB ?

Pas dans les versions actuelles. La prise en charge des deux a été retirée dans la version 11.0.0 du cœur. PostgreSQL à partir de la version 13.0 est la base de données prise en charge.

Combien coûte le scénario de MFA le moins cher sur mon propre serveur ?

Cent dollars par mois, car c'est le montant minimum de facturation de l'option MFA quel que soit le nombre d'utilisateurs. Au tarif de 0,01 USD par utilisateur actif, le minimum cesse de compter seulement au-dessus de dix mille utilisateurs mensuels.

Quand SuperTokens est-il un mauvais choix ?

Quand vous n'avez besoin que d'une connexion par mot de passe et sociale dans un petit projet, car trois pièces mobiles sont une complexité excessive. Quand vous travaillez sur un réseau coupé d'Internet et n'êtes pas sûr du format de la clé. Et quand votre plan produit suppose la multi-tenance et SAML dès le premier jour, car des deux avantages promis, l'ouverture et le coût nul, un seul survit alors.

À lire aussi