SuperTokens

SuperTokens

  • Docs
  • Discord
  • Blog

›Sessions

SIDEBAR_REPLACE_DOC_About this recipe

  • About this recipe

Quick setup

  • Frontend
  • Backend
  • Core

    • Self Hosted setup with Docker
    • Self Hosted setup without Docker
    • Managed Service

    Database Setup

    • MySQL
    • PostgreSQL
    • MongoDB
    • Rename database tables

Common customizations

  • Redirect To Auth Screen
  • Sign Out
  • SignUp Form

    • Prerequisite
    • Adding Extra Fields
    • Adding / Modifying field validators
    • Built in providers
    • Custom providers
    • Embed in a page
    • Terms of service & Privacy policy links
    • Show Sign Up by default

    SignIn Form

    • Prerequisite
    • Adding / Modifying field validators
    • Built in providers
    • Custom providers
    • Password managers
    • Embed in a page
  • Post sign up callbacks
  • Post sign in callbacks
  • User Roles

    • Assigning roles to users
    • Assigning roles to a session
    • Reading roles in an API
    • Reading roles in the frontend
    • Updating roles in a session

    Reset Password

    • About
    • Reset Password Email
    • Embed in a page

    Email Verification

    • About
    • Customising the email sent
    • Embed in a page

    Sessions

    • About
    • Storing session data
    • Session Verification in API
    • Revoking a session manually
    • Change session timeout
    • Checking if a session exists on the frontend
    • Get user information on the frontend
    • Fetching sessions for a user
    • Update JWT Payload
    • Update Session Data
    • Cookies and Https
    • Cookie Consent
    • Share sessions across sub domains
    • Anti CSRF
    • Same site cookies
    • JWT Signing key rotation
    • Access token blacklisting
    • Customizing Error Handling

    Styling

    • Changing Colours
    • Changing Style via CSS
    • Themes

    Changing base path

    • Website Base Path
    • API Base Path
  • User Pagination
  • Core

    • Adding API Keys
    • Tuning Performance
    • Logging

    Core CLI

    • Overview
    • Start
    • List
    • Stop
    • Uninstall

NextJS

  • About
  • 1. Configuration
  • 2. Showing Login UI
  • 3. Adding auth APIs
  • 4. Protecting a website route
  • 5. Session verification

    • 5a. Session verification in an API call
    • 5b. Session verification in getServerSideProps
  • 6. Next steps

SIDEBAR_REPLACE_DOC_Serverless Optimisation

  • Running on serverless env

SIDEBAR_REPLACE_DOC_SDKs API Reference

  • SDKs API Reference

Customizing Error Handling

SuperTokens session recipie can throw the following errors:

  • GENERAL_ERROR

    • This is a generic, something went wrong error. If this is thrown, the error will be propagated to your error handler.
  • UNAUTHORISED

    • When using the SuperTokens middleware, this error will automatically be handled - a status code indicating session expiry will be sent to the client.
    • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.
  • Interface

NodeJS
onUnauthorised:(message: string, request: Request, response: Response, next: NextFunction): void;

  • Example code
NodeJS
let SuperTokens = require("supertokens-node");
let Session = require("supertokens-node/recipe/session");

SuperTokens.init({
supertokens: {...},
appInfo: {...},
recipeList: [
Session.init({
errorHandlers: {
onUnauthorised?: (message, reqest, response, next) => {
// your custom code
},
}
})
]
});
  • TOKEN_THEFT_DETECTED

    • When using the SuperTokens middleware, this error will automatically be handled. The middleware will automatically revoke the session and send a session expired status code to the client.
    • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.
  • Interface

NodeJS
onTokenTheftDetected:(sessionHandle: string, userId: string, request: Request, response: Response, next: NextFunction): void;

  • Example Code
NodeJS
let SuperTokens = require("supertokens-node");
let Session = require("supertokens-node/recipe/session");

SuperTokens.init({
supertokens: {...},
appInfo: {...},
recipeList: [
Session.init({
errorHandlers: {
onTokenTheftDetected?: (sessionHandle, userId, req, res, next) => {
// your custom code
},
}
})
]
});
  • TRY_REFRESH_TOKEN
    • This error is thrown when the access token has expired, and to maintain the session, we must call the refresh API with the refresh session.
    • The refreshing happens automatically via our frontend SDK.
    • This function cannot be overridden at the moment.
← Access token blacklistingChanging Colours →