supertokens-website

This library implements the frontend part of user session management for websites. You can use this to make http(s) API calls to your backend that require an authenticated user.

Features:

• When you make an API call, and if the access token has expired, this library will automatically take care of refreshing the token for you. After successfully refreshing it, it will call your API with the new token again and return its response.
• Takes care of race conditions mentioned in the footer of this blog post.

Installation

To get started, you just need to do:

npm i --save supertokens-website

Usage

This library is to be used instead of fetch in places where the API requires authentication.

import * as SuperTokensRequest from "supertokens-website";

SuperTokensRequest.init(refreshTokenURL, sessionExpiredStatusCode)

• To be called at least once before any http request is made from your frontend that uses this library. For example, if your website is a single page ReactJS app, then you can call this in the constructor of the root component.

// @params refreshTokenURL: this is the path to API endpoint that is responsible for refreshing the session when the access token expires.
// @params sessionExpiredStatusCode: this is the status code that will be sent by any API that detects session expiry.
// @returns void
SuperTokensRequest.init("/api/refreshtoken", 440)

SuperTokensRequest.get(url, config)

• send a GET request to this url - to be used only with your app's APIs

// @params url: endpoint to your GET API
// @params config: this is same as fetch config
// @returns Promise
SuperTokensRequest.get("/someAPI", config).then(response => {
  // API response.
}).catch(err => {
  // handle error
});

SuperTokensRequest.post(url, config)

• send a POST request to this url - to be used only with your app's APIs

// @params url: endpoint to your POST API
// @params config: this is same as fetch config
// @returns Promise
SuperTokensRequest.post("/someAPI", config).then(response => {
  // API response.
}).catch(err => {
  // handle error
});

SuperTokensRequest.delete(url, config)

• send a DELETE request to this url - to be used only with your app's APIs

// @params url: endpoint to your DELETE API
// @params config: this is same as fetch config
// @returns Promise
SuperTokensRequest.delete("/someAPI", config).then(response => {
  // API response.
}).catch(err => {
  // handle error
});

SuperTokensRequest.put(url, config)

• send a PUT request to this url - to be used only with your app's APIs

// @params url: endpoint to your PUT API
// @params config: this is same as fetch config
// @returns Promise
SuperTokensRequest.put("/someAPI", config).then(response => {
  // API response.
}).catch(err => {
  // handle error
});

SuperTokensRequest.doRequest(func)

• use this function to send a request using any other http method that is not mentioned above

// @params func: a function that returns a Promise returned by calling the fetch function
// @returns Promise
SuperTokensRequest.doRequest(() => fetch(...)).then(response => {
  // API response.
}).catch(err => {
  // handle error
});

SuperTokensRequest.attemptRefreshingSession()

• use this function when you want to manually refresh the session.

// @params func: a function that returns a Promise returned by calling the fetch function
// @returns Promise
SuperTokensRequest.attemptRefreshingSession().then(success => {
  if (success) {
    // session may have refreshed successfully 
  } else {
    // user has been logged out. Redirect to login page
  }
}).catch(err => {
  // handle error
});

Example code & Demo

You can play around with the demo project that uses this and the supertokens-node-mysql-ref-jwt library. The demo demonstrates how this package behaves when it detects auth token theft (and the best part - you are the hacker here, muahahaha!)

Making changes

This library is written in TypeScript (TS). When you make any changes to the .ts files in the root folder, run the following command to compile to .js:

tsc -p tsconfig.json

Support, questions and bugs

For now, we are most reachable via [e-mail], via the GitHub issues feature and our Discord server.

Authors

Created with :heart: 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 [e-mail], until our website is ready :grinning: