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 recipe function to add information into the context indicating that it's a sign up call:

NodeJS

import SuperTokens from "supertokens-node";
import ThirdParty from "supertokens-node/recipe/thirdparty";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        ThirdParty.init({
            signInAndUpFeature: { 
                providers: [/*...*/]
            },
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        signInUp: async function (input) {
                            let resp = await originalImplementation.signInUp(input);
                            if (resp.status === "OK" && resp.createdNewUser) {
                                /*
                                 * This is called during the signInUp API for third party login,
                                 * but before calling the createNewSession function.
                                 * At the start of the API, we do not know if it will result in a 
                                 * sign in or a sign up, so we cannot override the API function.
                                 * Instead, we override the recipe function as shown here,
                                 * and then set the relevant context only if it's a new user.
                                 */

                                /*
                                 * by default, the userContext Dict is {},
                                 * we change it to {isSignUp: true}, since this is called in the 
                                 * sign up API, and this will tell the create_new_session function
                                 * (which will be called next)
                                 * to not create a new session in case input.userContext.isSignUp == true
                                 */
                                input.userContext.isSignUp = true;
                            }
                            return resp;
                        },
                    }
                },
            }
        })
    ]
});

GoLang

import (
    "github.com/supertokens/supertokens-golang/recipe/thirdparty"
    "github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            thirdparty.Init(&tpmodels.TypeInput{
                Override: &tpmodels.OverrideStruct{
                    Functions: func(originalImplementation tpmodels.RecipeInterface) tpmodels.RecipeInterface {
                        ogSignInUp := *originalImplementation.SignInUp

                        (*originalImplementation.SignInUp) = func(thirdPartyID, thirdPartyUserID string, email string, userContext supertokens.UserContext) (tpmodels.SignInUpResponse, error) {
                            resp, err := ogSignInUp(thirdPartyID, thirdPartyUserID, email, userContext)

                            if err != nil {
                                return tpmodels.SignInUpResponse{}, err
                            }

                            if resp.OK != nil && resp.OK.CreatedNewUser {
                                /*
                                 * This is called during the signInUp API for third party login,
                                 * but before calling the createNewSession function.
                                 * At the start of the API, we do not know if it will result in a
                                 * sign in or a sign up, so we cannot override the API function.
                                 * Instead, we override the recipe function as shown here,
                                 * and then set the relevant context only if it's a new user.
                                 */

                                /*
                                 * by default, the userContext Dict is {},
                                 * we change it to {isSignUp: true}, since this is called in the 
                                 * sign up API, and this will tell the create_new_session function
                                 * (which will be called next)
                                 * to not create a new session in case (*userContext)["isSignUp"] == True
                                 */
                                (*userContext)["isSignUp"] = true
                            }
                            return resp, nil
                        }

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

Python

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import thirdparty
from supertokens_python.recipe.thirdparty.interfaces import RecipeInterface
from typing import Dict, Any

def override_thirdparty_functions(original_implementation: RecipeInterface):
    original_sign_in_up = original_implementation.sign_in_up

    async def sign_in_up(third_party_id: str, third_party_user_id: str, email: str,
                         user_context: Dict[str, Any]):
        response = await original_sign_in_up(
            third_party_id, third_party_user_id, email, user_context)

        # This is called during the sign_in_up API for third party login,
        # but before calling the create_new_session function.
        # At the start of the API, we do not know if it will result in a
        # sign in or a sign up, so we cannot override the API function.
        # Instead, we override the recipe function as shown here,
        # and then set the relevant context only if it's a new user.

        # by default, the userContext Dict is {},
        # we change it to {isSignUp: true}, since this is called in the
        # sign up API, and this will tell the create_new_session function
        # (which will be called next)
        # to not create a new session in case userContext["isSignUp"] is True
        if response.created_new_user:
            user_context["isSignUp"] = True

        return response

    original_implementation.sign_in_up = sign_in_up
    return original_implementation


init(
    app_info=InputAppInfo(
        api_domain="...", app_name="...", website_domain="..."),
    framework='...',  
    recipe_list=[
        thirdparty.init(
            sign_in_and_up_feature=...,  
            override=thirdparty.InputOverrideConfig(
                functions=override_thirdparty_functions
            )
        )
    ]
)

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 ThirdParty from "supertokens-node/recipe/thirdparty";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        ThirdParty.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/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/recipe/thirdparty"
    "github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

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

                        (*originalImplementation.CreateNewSession) = func(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(res, userID, accessTokenPayload, sessionData, userContext)
                        }

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

Python

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import thirdparty
from supertokens_python.recipe.session.interfaces import RecipeInterface, SessionClaimValidator, SessionClaim
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=[
        thirdparty.init( 
            # see previous step...
        ),
        session.init(
            override=session.InputOverrideConfig(
                functions=override_session_functions
            )
        )
    ]
)


class EmptySession(session.SessionContainer):
    def __init__(self, recipe_implementation: RecipeInterface):
        super().__init__(recipe_implementation, "", "", "", {})

    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.

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.