Which frontend SDK do you use?

supertokens-web-js / mobile

supertokens-auth-react

User Context

important

This feature is only available for SDKs versions:

• NodeJS >= v9.0
• Python >= v0.5
• GoLang >= v0.5

How does it work?

This is a powerful concept that allows you to pass information across recipe and / or API functions so that customisations can be made based on a specific "execution context".

For example, you may want to disable creation of a session during sign up so that the user has to login again post sign up. In order to do that, the createNewSession recipe function (from the Session recipe) will have to know that it's being called from the sign up API and return an empty session (which is equal to no session). This is as opposed to it being called from the sign in API, in which it should continue with normal functionalty.

In order to achieve this, all the API interface and recipe interface functions take a parameter called userContext which is by default an empty object. When overriding the functions, you can add anything in this object and that information is carried onto the next set of functions being called in the API

Example use

Let's take the example mentioned above and implement it in the context of this recipe. First, we override the sign up APIs to add information into the context indicating that it's a sign up API call:

NodeJS

import SuperTokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        EmailPassword.init({
            override: {
                apis: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        // override sign up using email / password 
                        signUpPOST: async function (input) {
                            if (originalImplementation.signUpPOST === undefined) {
                                throw new Error("Should never come here");
                            }

                            // by default, the userContext object is {},
                            // we change it to {isSignUp: true}, since this is the
                            // sign up API, and this will tell the createNewSession function
                            // (being called inside originalImplementation.signUpPOST)
                            // to not create a new session in case userContext.isSignUp === true
                            input.userContext.isSignUp = true;
                            return originalImplementation.signUpPOST(input);
                        },
                    }
                }
            }
        })
    ]
});

GoLang

import (
    "github.com/supertokens/supertokens-golang/recipe/emailpassword"
    "github.com/supertokens/supertokens-golang/recipe/emailpassword/epmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            emailpassword.Init(&epmodels.TypeInput{
                Override: &epmodels.OverrideStruct{
                    APIs: func(originalImplementation epmodels.APIInterface) epmodels.APIInterface {
                        ogSignUpPOST := *originalImplementation.SignUpPOST

                        (*originalImplementation.SignUpPOST) = func(formFields []epmodels.TypeFormField, options epmodels.APIOptions, userContext supertokens.UserContext) (epmodels.SignUpPOSTResponse, error) {
                            // by default, the userContext object is {},
                            // we change it to {isSignUp: true}, since this is the
                            // sign up API, and this will tell the CreateNewSession function
                            // (being called inside ogSignUpPOST)
                            // to not create a new session in case userContext["isSignUp"] == true
                            (*userContext)["isSignUp"] = true
                            return ogSignUpPOST(formFields, options, userContext)
                        }

                        return originalImplementation
                    },
                },
            }),
        },
    })
}

Python

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import emailpassword
from supertokens_python.recipe.emailpassword.interfaces import APIInterface, APIOptions
from supertokens_python.recipe.emailpassword.types import FormField
from typing import List, Dict, Any



def override_emailpassword_apis(original_implementation: APIInterface):
    original_sign_up_post = original_implementation.sign_up_post

    async def sign_up_post(form_fields: List[FormField],
                           api_options: APIOptions, user_context: Dict[str, Any]):

        # by default, the userContext Dict is {},
        # we change it to {isSignUp: true}, since this is the
        # sign up API, and this will tell the create_new_session function
        # (being called inside original_sign_up_post)
        # to not create a new session in case userContext["isSignUp"] is True
        user_context["isSignUp"] = True
        return await original_sign_up_post(form_fields, api_options, user_context)

    original_implementation.sign_up_post = sign_up_post
    return original_implementation


init(
    app_info=InputAppInfo(
        api_domain="...", app_name="...", website_domain="..."),
    framework='...',  
    recipe_list=[
        emailpassword.init(
            override=emailpassword.InputOverrideConfig(
                apis=override_emailpassword_apis
            )
        )
    ]
)

Then we consume that context in the createNewSession function to return an empty function in case the userContext.isSignUp is true

NodeJS

import SuperTokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        EmailPassword.init({/* See previous step... */}),
        Session.init({
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        createNewSession: async function (input) {
                            if (input.userContext.isSignUp) {
                                /**
                                 * The execution will come here only in case
                                 * a sign up API is calling this function. This is because
                                 * only then will the input.userContext.isSignUp === true
                                 * (see above code).
                                 */
                                return {
                                    getAccessToken: () => "",
                                    getAccessTokenPayload: () => null,
                                    getExpiry: async () => -1,
                                    getHandle: () => "",
                                    getSessionData: async () => null,
                                    getTimeCreated: async () => -1,
                                    getUserId: () => "",
                                    revokeSession: async () => { },
                                    updateAccessTokenPayload: async () => { },
                                    updateSessionData: async () => { },
                                    mergeIntoAccessTokenPayload: async () => { },
                                    assertClaims: async () => { },
                                    fetchAndSetClaim: async () => { },
                                    getClaimValue: async () => undefined,
                                    setClaimValue: async () => { },
                                    removeClaim: async () => { },
                                }; // this is an empty session. It won't result in a session being created for the user.
                            }
                            return originalImplementation.createNewSession(input);
                        }
                    }
                }
            }
        })
    ]
});

GoLang

import (
    "net/http"

    "github.com/supertokens/supertokens-golang/recipe/emailpassword"
    "github.com/supertokens/supertokens-golang/recipe/emailpassword/epmodels"
    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            emailpassword.Init(&epmodels.TypeInput{ /* See previous step... */ }),
            session.Init(&sessmodels.TypeInput{
                Override: &sessmodels.OverrideStruct{
                    Functions: func(originalImplementation sessmodels.RecipeInterface) sessmodels.RecipeInterface {
                        ogCreateNewSession := *originalImplementation.CreateNewSession

                        (*originalImplementation.CreateNewSession) = func(req *http.Request, res http.ResponseWriter, userID string, accessTokenPayload, sessionData map[string]interface{}, userContext supertokens.UserContext) (sessmodels.SessionContainer, error) {
                            _, isSignUp := (*userContext)["isSignUp"]
                            if isSignUp {
                                /**
                                 * The execution will come here only in case
                                 * a sign up API is calling this function. This is because
                                 * only then will the (*userContext)["isSignUp"] === true
                                 * (see above code).
                                 */
                                return nil, nil // this is an empty session. It won't result in a session being created for the user.
                            }

                            return ogCreateNewSession(req, res, userID, accessTokenPayload, sessionData, userContext)
                        }

                        return originalImplementation
                    },
                },
            }),
        },
    })
}

Python

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import emailpassword
from supertokens_python.recipe.session.interfaces import RecipeInterface, SessionClaimValidator, SessionClaim
from supertokens_python.recipe.session.recipe_implementation import RecipeImplementation
from typing import Dict, Any, Union, List, TypeVar
from supertokens_python.recipe import session

_T = TypeVar("_T")

def override_session_functions(original_implementation: RecipeInterface):
    original_create_new_session = original_implementation.create_new_session

    async def create_new_session(request: Any, user_id: str,
                                 access_token_payload: Union[None, Dict[str, Any]],
                                 session_data: Union[None, Dict[str, Any]], user_context: Dict[str, Any]):
        if user_context["isSignUp"] is True:
            # The execution will come here only in case
            # a sign up API is calling this function. This is because
            # only then will the user_context["isSignUp"] === true
            # (see above code).
            return EmptySession(original_implementation)

        return await original_create_new_session(request, user_id, access_token_payload, session_data, user_context)
    original_implementation.create_new_session = create_new_session
    return original_implementation


init(
    app_info=InputAppInfo(
        api_domain="...", app_name="...", website_domain="..."),
    framework='...',  
    recipe_list=[
        emailpassword.init(
            # see previous step...
        ),
        session.init(
            override=session.InputOverrideConfig(
                functions=override_session_functions
            )
        )
    ]
)


class EmptySession(session.SessionContainer):
    def __init__(self, recipe_implementation: RecipeInterface):
        assert isinstance(recipe_implementation, RecipeImplementation)
        super().__init__(recipe_implementation, recipe_implementation.config, "", "", "", {}, "cookie")

    async def revoke_session(self, user_context: Union[Any, None] = None) -> None:
        pass

    async def get_session_data(self, user_context: Union[Dict[str, Any], None] = None) -> Dict[str, Any]:
        return {}

    async def update_session_data(self, new_session_data: Dict[str, Any], user_context: Union[Dict[str, Any], None] = None) -> None:
        pass

    async def update_access_token_payload(self, new_access_token_payload: Dict[str, Any], user_context: Union[Dict[str, Any], None] = None) -> None:
        pass

    def get_user_id(self, user_context: Union[Dict[str, Any], None] = None) -> str:
        return ""

    def get_access_token_payload(
            self, user_context: Union[Dict[str, Any], None] = None) -> Dict[str, Any]:
        return {}

    def get_handle(self, user_context: Union[Dict[str, Any], None] = None) -> str:
        return ""

    def get_access_token(self, user_context: Union[Dict[str, Any], None] = None) -> str:
        return ""

    async def get_time_created(self, user_context: Union[Dict[str, Any], None] = None) -> int:
        return -1

    async def get_expiry(self, user_context: Union[Dict[str, Any], None] = None) -> int:
        return -1

    async def assert_claims(
        self,
        claim_validators: List[SessionClaimValidator],
        user_context: Union[Dict[str, Any], None] = None,
    ) -> None:
        pass

    async def fetch_and_set_claim(
        self, claim: SessionClaim[Any], user_context: Union[Dict[str, Any], None] = None
    ) -> None:
        pass

    async def set_claim_value(
        self,
        claim: SessionClaim[_T],
        value: _T,
        user_context: Union[Dict[str, Any], None] = None,
    ) -> None:
        pass

    async def get_claim_value(
        self, claim: SessionClaim[_T], user_context: Union[Dict[str, Any], None] = None
    ) -> Union[_T, None]:
        pass

    async def remove_claim(
        self,
        claim: SessionClaim[Any],
        user_context: Union[Dict[str, Any], None] = None,
    ) -> None:
        pass

    async def merge_into_access_token_payload(
        self, access_token_payload_update: Dict[str, Any], user_context: Union[Dict[str, Any], None] = None
    ) -> None:
        pass

As a summary, when the sign up API is called, the initial value of userContext is an empty object. We change that user context to add the isSignUp field so that that information can be communicated to the createNewSession function.

When that is called, that function checks if isSignUp === true, and if it is, it doesn't call the original implementation, and instead, just returns an empty session. This way, we don't create a session if the user is signing up, but we do create one if the user is signing in.

Note that there are other ways of achiving this, but the above showcases how we can use user context to communicate across recipes and across API & Recipe functions.

Default information in the user context object

This section describes any default content added to the user context object for you to consume.

Backend

{
    _default: {
        /* 
        This is the request object that allows you to read the body / origin / headers of the API request.

        It is optional and will be defined only if the function you are overriding is called during an API.
        */
        request
    }
}

Frontend

The userContext object is empty by default.