SuperTokens

SuperTokens

  • Docs
  • Discord
  • Blog

›Sessions

SIDEBAR_REPLACE_DOC_Introduction

  • Introduction

Quick setup

  • Video tutorial
  • Frontend
  • Backend

Common customizations

  • Sign Out
  • Sign Up Form

    • About
    • Adding Extra Fields
    • Adding / Modifying field validators
    • Embed in a page
    • Handling signup success
    • Terms of service & Privacy policy links

    Sign In Form

    • About
    • Adding / Modifying field validators
    • Password managers
    • Embed in a page
    • Show Sign In by default

    Reset Password

    • About
    • Reset password email
    • Embed in a page

    Email Verification

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

    Sessions

    • About
    • Cookie Consent
    • Creating a new session
    • Session Verification in API
    • Change session timeout
    • Checking if a session exists on the frontend
    • Get user information on the frontend
    • Using with FaunaDB
    • Cookies and Https
    • 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

    Multi Tenancy

    • About
    • One login, many sub domains
    • One login per sub domain
  • User Pagination

NextJS

  • SuperTokens with NextJS
  • Deploy with Vercel
  • Deploy with Netlify

Customizing Error Handling

SuperTokens session recipie can throw the following errors:

  • GENERAL_ERROR

    • The way to handle this error is to simply send a status code of 500. Or try to call the function once again after a while.
  • BAD_INPUT_ERROR

    • This is thrown if the request to a default API has bad input. The middleware automatically returns an http response with status code 400.
  • UNAUTHORISED

    • When using the SuperTokens middleware, this error will automatically be handled. The middleware will automatically clear auth cookies.

    • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.

    • Nodejs code

      • Interface
      onUnauthorised:(message: string, request: Request, response: Response, next: NextFunction): void;
      
      
      • Example code
      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 reply with a session expired status code response with an error message "token theft detected".

    • This behavior can be overridden by supplying a custom error handler when initializing the Session Recipe in your backend code.

    • Nodejs code

      • Interface
      onTokenTheftDetected:(sessionHandle: string, userId: string, request: Request, response: Response, next: NextFunction): void;
      
      
      • Example Code
      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.
← Access token blacklistingChanging Colours →