Get unlimited public & private packages + team-based management with npm Teams.Learn more »


3.2.0 • Public • Published

SuperTokens banner

License: MIT chat on Discord

Master CircleCI Dev CircleCI

This library implements user session management for websites that run on NodeJS and MongoDB. This is meant to be used with your backend code. If you do not use these technologies, please checkout our website to find the right library for you..

The protocol SuperTokens uses is described in detail in this article

The library has the following features:

  • It uses short-lived access tokens (JWT) and long-lived refresh tokens (Opaque).
  • Protects against: XSS, Brute force, Session fixation, JWT signing key compromise, Data theft from database, CSRF and session hijacking.
  • Token theft detection: SuperTokens is able to detect token theft in a robust manner. Please see the article mentioned above for details on how this works.
  • Complete auth token management - It only stores the hashed version of refresh tokens in the database, so even if someone (an attacker or an employee) gets access to the collection containing them, they would not be able to hijack any session.
  • Automatic JWT signing key generation (if you don't provide one), management and rotation - Periodic changing of this key enables maximum security as you don't have to worry much in the event that this key is compromised. Also note that doing this change will not log any user out 😀
  • Complete cookie management - Takes care of making them secure and HttpOnly. Also removes, adds and edits them whenever needed. You do not have to worry about cookies and its security anymore!
  • Efficient in terms of space complexity - Needs to store just one document in a MongoDB collection per logged in user per device.
  • Efficient in terms of time complexity - Minimises the number of DB lookups (most requests do not need a database call to authenticate at all if blacklisting is false - which is the default)
  • Built-in support for handling multiple devices per user.
  • Built-in synchronisation in case you are running multiple node processes.
  • Easy to use (see auth-demo), with well documented, modularised code and helpful error messages!
  • Using this library, you can keep a user logged in for however long you want - without worrying about any security consequences.



Please see our Documentation website

Making changes

Please see our Contributing guide


To test this library, you need Node and MongoDB running on your system.

npm install -d
npm test

See our Contributing guide for more information.

Future work

  • Enable this to work with mobile apps as well.
  • To implement info, debug and error logs in a better way.
  • Add scaling metrics
  • IP change detection invalidates access token, so that thefts get caught sooner, or attacker get's logged out, while keeping the actual user logged in (Thanks to Aervue)

Support, questions and bugs

We are most accessible via, via the GitHub issues feature and our Discord server.

Click here to see more information.


Created with ❤️ by the folks at SuperTokens. We are a startup passionate about security and solving software challenges in a way that's helpful for everyone! Please feel free to give us feedback at, until our website is ready 😀


npm i supertokens-node-mongo-ref-jwt

DownloadsWeekly Downloads






Unpacked Size

461 kB

Total Files


Last publish


  • avatar