Allow users to change their email

caution

SuperTokens does not provide the UI for users to update their email, you will need to create the UI and setup a route on your backend to have this functionality.

In this section we will go over how you can create a route on your backend which can update a user's email. Calling this route will check if the new email is valid and not already in use and proceed to update the user's account with the new email. There are two types of flows here:

Flow 1: Update email without verifying the new email.#

In this flow a user is allowed to update their accounts email without verifying the new email id.

Step 1: Creating the `/change-email` route#

You will need to create a route on your backend which is protected by the session verification middleware, this will ensure that only a authenticated user can access the protected route.
To learn more about how to use the session verification middleware for other frameworks click here

NodeJS
GoLang
Python
Other Frameworks

import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-email", verifySession(), async (req: SessionRequest, res: express.Response) => {
    // TODO: see next steps
})

import (
    "net/http"

    "github.com/supertokens/supertokens-golang/recipe/session"
)

// the following example uses net/http
func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changeEmailAPI).ServeHTTP(rw, r)
    })
}

func changeEmailAPI(w http.ResponseWriter, r *http.Request) {
    // TODO: see next steps
}

# the following example uses flask
from supertokens_python.recipe.session.framework.flask import verify_session
from flask import Flask

app = Flask(__name__)

@app.route('/change-email', methods=['POST']) 
@verify_session()
def change_email():
    pass # TODO: see next steps

Step 2: Validate the new email and update the account#

Validate the input email.
Update the account with the input email.

NodeJS
GoLang
Python
Other Frameworks

// the following example uses express
import Passwordless from "supertokens-node/recipe/passwordless";
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-email", verifySession(), async (req: SessionRequest, res: express.Response) => {

    let session = req.session!;
    let email = req.body.email;

    // Validate the input email
    if (!isValidEmail(email)) {
        // TODO: handle invalid email error
        return 
    }
    
    // Update the email
    let resp = await Passwordless.updateUser({
        userId: session.getUserId(),
        email: email
    })

    if (resp.status === "OK") {
        // TODO: send successfully updated email response
        return 
    }
    if (resp.status === "EMAIL_ALREADY_EXISTS_ERROR") {
        // TODO: handle error that email exists with another account.
        return
    }
    throw new Error("Should never come here");

})

function isValidEmail(email: string) {
    let regexp = new RegExp(
        /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
    );
    return regexp.test(email);
}

import (
    "encoding/json"
    "log"
    "net/http"
    "regexp"

    "github.com/supertokens/supertokens-golang/recipe/passwordless"
    "github.com/supertokens/supertokens-golang/recipe/session"
)

type RequestBody struct {
    email string
}

// the following example uses net/http
func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changeEmailAPI).ServeHTTP(rw, r)
    })
}

func changeEmailAPI(w http.ResponseWriter, r *http.Request) {
    sessionContainer := session.GetSessionFromRequestContext(r.Context())

    var requestBody RequestBody
    err := json.NewDecoder(r.Body).Decode(&requestBody)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
    }

    // validate the input email
    if !isValidEmail(requestBody.email) {
        // TODO: handle invalid email error
        return
    }

    // update the email
    userId := sessionContainer.GetUserID()
    updateResponse, err := passwordless.UpdateUser(userId, &requestBody.email, nil)

    if err != nil {
        // TODO: handle error
    }

    if updateResponse.OK != nil {
        // TODO: send successfully updated email response
        return
    }

    if updateResponse.EmailAlreadyExistsError != nil {
        // TODO: handle error that email exists with another account
        return
    }

    log.Fatal("should not reach here")

}

func isValidEmail(email string) bool {
    emailCheck, err := regexp.Match(`^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$`, []byte(email))
    if err != nil {
        return false
    }
    return emailCheck
}

from supertokens_python.recipe.session.framework.flask import verify_session
from supertokens_python.recipe.session import SessionContainer
from supertokens_python.recipe.passwordless.syncio import update_user
from supertokens_python.recipe.passwordless.interfaces import UpdateUserOkResult, UpdateUserEmailAlreadyExistsError
from flask import g, request, Flask
from re import fullmatch

app = Flask(__name__)

@app.route('/change-email', methods=['POST']) 
@verify_session()
def change_email():
    session: SessionContainer = g.supertokens

    request_body = request.get_json()

    # validate the input email
    if not is_valid_email(request_body["email"]): 
        # TODO: handle invalid email error
        return

    # update the users email
    user_id = session.get_user_id()
    update_response = update_user(user_id, email=request_body["email"]) 

    if isinstance(update_response, UpdateUserOkResult):
        # TODO send successful email update response
        return

    if isinstance(update_response, UpdateUserEmailAlreadyExistsError):
        # TODO handle error, email already exists
        return

    raise Exception("Should never reach here")


async def is_valid_email(value: str) -> bool:
    return (
        fullmatch(
            r'^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,'
            r"3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$",
            value,
        )
        is not None
    )

Flow 2: Updating email after verifying the new email.#

In this flow the user's account is updated once they have verified the new email.

Step 1: Creating the `/change-email` route#

You will need to create a route on your backend which is protected by the session verification middleware, this will ensure that only a authenticated user can access the protected route.
To learn more about how to use the session verification middleware for other frameworks click here

NodeJS
GoLang
Python
Other Frameworks

import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-email", verifySession(), async (req: SessionRequest, res: express.Response) => {
    // TODO: see next steps
})

import (
    "net/http"

    "github.com/supertokens/supertokens-golang/recipe/session"
)

// the following example uses net/http
func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changeEmailAPI).ServeHTTP(rw, r)
    })
}

func changeEmailAPI(w http.ResponseWriter, r *http.Request) {
    // TODO: see next steps
}

# the following example uses flask
from supertokens_python.recipe.session.framework.flask import verify_session
from flask import Flask

app = Flask(__name__)

@app.route('/change-email', methods=['POST']) 
@verify_session()
def change_password():
    pass # TODO: see next steps

Step 2: Validate the email and initiate the email verification flow#

Validate the input email
Check if the input email is associated with an account.
Check if the input email is already verified.
If the email is NOT verified, create and send the verification email.
If the email is verified, update the account with the new email.

NodeJS
GoLang
Python
Other Frameworks

import Passwordless from "supertokens-node/recipe/passwordless";
import EmailVerification from "supertokens-node/recipe/emailverification";
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-email", verifySession(), async (req: SessionRequest, res: express.Response) => {

    let session = req.session!;
    let email = req.body.email;

    // validate the input email
    if (!isValidEmail(email)) {
        return res.status(400).send("Email is invalid");
    }

    // Check if the new email is already associated with another user.
    // If it is, then we throw an error. If it's already associated with this user,
    // then we return a success response with an appropriate message.
    let existingUser = await Passwordless.getUserByEmail(email);
    if (existingUser !== undefined) {
        if (existingUser.id === session.getUserId()) {
            // TODO send successful response that email already belongs to this account.
            return
        } else {
            // TODO handle error, email already exists with another user.
            return
        }
    }

    // Then, we check if the email is verified for this user ID or not.
    // It is important to understand that SuperTokens stores email verification
    // status based on the user ID AND the email, and not just the email.
    let isVerified = await EmailVerification.isEmailVerified(session.getUserId(), email);

    if (!isVerified) {
        // Now we create and send the email verification link to the user for the new email.
        let tokenInfo = await EmailVerification.createEmailVerificationToken(session.getUserId(), email);

        if (tokenInfo.status === "OK") {
            let link = "<YOUR_WEBSITE_DOMAIN>/auth/verify-email?token=" + tokenInfo.token;

            await EmailVerification.sendEmail({
                emailVerifyLink: link,
                type: "EMAIL_VERIFICATION",
                user: {
                    id: session.getUserId(),
                    email: email,
                },
            });

            // TODO send successful response that email verification email sent.
            return 
        }
        // else case is that the email is already verified (which can happen cause
        // of some race condition). So we continue below..
    }

    // Since the email is verified, we try and do an update
    let resp = await Passwordless.updateUser({
        userId: session.getUserId(),
        email: email,
    });

    if (resp.status === "OK") {
        // TODO send successful response that email updated.
        return
    }
    if (resp.status === "EMAIL_ALREADY_EXISTS_ERROR") {
        // Technically it should never come here cause we have
        // checked for this above already, but just in case (some sort of race condition).
        // TODO handle error, email already exists with another user.
        return 
    }

    throw new Error("Should never come here");

})

function isValidEmail(email: string) {
    let regexp = new RegExp(
        /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
    );
    return regexp.test(email);
}


import (
    "encoding/json"
    "log"
    "net/http"
    "regexp"

    "github.com/supertokens/supertokens-golang/ingredients/emaildelivery"
    "github.com/supertokens/supertokens-golang/recipe/emailverification"
    "github.com/supertokens/supertokens-golang/recipe/passwordless"
    "github.com/supertokens/supertokens-golang/recipe/session"
)

type RequestBody struct {
    email string
}

// the following example uses net/http
func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changeEmailAPI).ServeHTTP(rw, r)
    })
}

func changeEmailAPI(w http.ResponseWriter, r *http.Request) {
    sessionContainer := session.GetSessionFromRequestContext(r.Context())

    var requestBody RequestBody
    err := json.NewDecoder(r.Body).Decode(&requestBody)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
    }

    // validate the input email
    if !isValidEmail(requestBody.email) {
        // TODO: handle invalid email error
        return
    }

    // Check if the new email is already associated with another email-password user.
    // If it is, then we throw an error. If it's already associated with this user,
    // then we return a success response with an appropriate message.
    userId := sessionContainer.GetUserID()
    existingUser, err := passwordless.GetUserByEmail(requestBody.email)

    if err != nil {
        // TODO: handle error
    }

    if existingUser != nil {
        if existingUser.ID == userId {
            // TODO: send successful response, email already belongs to this account.
        }
        // TODO: handle error, email already exists with another account
    }

    // Then, we check if the email is verified for this user ID or not.
    // It is important to understand that SuperTokens stores email verification
    // status based on the user ID AND the email, and not just the email.
    isVerified, err := emailverification.IsEmailVerified(userId, &requestBody.email)

    if err != nil {
        // TODO: handle error
    }

    if !isVerified {
        // Now we create and send the email verification link to the user for the new email.
        tokenInfo, err := emailverification.CreateEmailVerificationToken(userId, &requestBody.email)
        if err != nil {
            // TODO: handle error
        }

        if tokenInfo.OK != nil {
            link := "<YOUR_WEBSITE_DOMAIN>/auth/verify-email?token=" + tokenInfo.OK.Token

            err := emailverification.SendEmail(emaildelivery.EmailType{
                EmailVerification: &emaildelivery.EmailVerificationType{
                    User: emaildelivery.User{
                        ID:    userId,
                        Email: requestBody.email,
                    },
                    EmailVerifyLink: link,
                },
            })

            if err != nil {
                // TODO: handle error
            }
        }
        // else case is that the email is already verified (which can happen cause
        // of some race condition). So we continue below..
    }

    // Since the email is verified, we try and do an update
    updateResponse, err := passwordless.UpdateUser(userId, &requestBody.email, nil)

    if err != nil {
        // TODO: handle error
    }

    if updateResponse.OK != nil {
        // TODO: send successfully updated email response
        return
    }

    if updateResponse.EmailAlreadyExistsError != nil {
        // Technically it should never come here cause we have
        // checked for this above already, but just in case (some sort of race condition).
        // TODO: handle error, email already exists for another account
        return
    }

    log.Fatal("should not reach here")

}

func isValidEmail(email string) bool {
    emailCheck, err := regexp.Match(`^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$`, []byte(email))
    if err != nil {
        return false
    }
    return emailCheck
}

from supertokens_python.recipe.session.framework.flask import verify_session
from supertokens_python.recipe.session import SessionContainer
from supertokens_python.recipe.passwordless.syncio import ( 
    get_user_by_email,
    update_user
)
from supertokens_python.recipe.passwordless.interfaces import (
    UpdateUserOkResult,
    UpdateUserEmailAlreadyExistsError,
)

from supertokens_python.recipe.emailverification.syncio import (
    is_email_verified,
    create_email_verification_token,
    send_email,   
)

from supertokens_python.recipe.emailverification.types import (
    EmailTemplateVars,
    VerificationEmailTemplateVarsUser
)

from supertokens_python.recipe.emailverification.interfaces import (
    CreateEmailVerificationTokenOkResult,
)

from flask import g, request, Flask
from re import fullmatch

app = Flask(__name__)

@app.route('/change-email', methods=['POST']) 
@verify_session()
def change_email():
    session: SessionContainer = g.supertokens 

    request_body = request.get_json()

    # validate the input email
    if not is_valid_email(request_body["email"]): 
        # TODO: handle invalid email error
        return

    # Check if the new email is already associated with another user.
    # If it is, then we throw an error. If it's already associated with this user,
    # then we return a success response with an appropriate message.
    existing_user = get_user_by_email(request_body["email"]) 
    user_id = session.get_user_id()
    if existing_user is not None:
        if existing_user.user_id != session.get_user_id():
            # TODO send successful response that email already belongs to this account
            return
        
        # TODO handle error, email already exists with another account
        return

    # Then, we check if the email is verified for this user ID or not.
    # It is important to understand that SuperTokens stores email verification
    # status based on the user ID AND the email, and not just the email.
    is_verified = is_email_verified(user_id, request_body["email"]) 
    
    if not is_verified:
        # Create and send the email verification link to the user for the new email.
        token_info = create_email_verification_token(user_id, request_body["email"]) 
        
        if isinstance(token_info, CreateEmailVerificationTokenOkResult):
            link = "<YOUR_WEBSITE_DOMAIN>/auth/verify-email?token={token_info.token}"
            
            send_email(EmailTemplateVars(VerificationEmailTemplateVarsUser(user_id=user_id, email=request_body["email"]), link, {}), None) 
            
            # TODO send successful email verification response
            return
    # else case is that the email is already verified (which can happen cause of some race condition). So we continue below..
    
    # update the users email
    update_response = update_user(user_id, email=request_body["email"]) 

    if isinstance(update_response, UpdateUserOkResult):
        # TODO send successful email update response
        return

    if isinstance(update_response, UpdateUserEmailAlreadyExistsError):
        # Technically it should never come here cause we have
        # checked for this above already, but just in case (some sort of race condition).
        # TODO handle error, email already exists
        return


    raise Exception("Should never reach here")


async def is_valid_email(value: str) -> bool:
    return (
        fullmatch(
            r'^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,'
            r"3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$",
            value,
        )
        is not None
    )

Step 3: Override the `verifyEmailPost` API to update the user's account on successful email verification#

Update the accounts email on successful email verification.

NodeJS
GoLang
Python
Other Frameworks

import SuperTokens from "supertokens-node";
import Passwordless from "supertokens-node/recipe/passwordless";
import EmailVerification from "supertokens-node/recipe/emailverification";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    Passwordless.init({
        flowType: "USER_INPUT_CODE_AND_MAGIC_LINK",
        contactMethod: "EMAIL_OR_PHONE"
    }),
    EmailVerification.init({
        mode: "REQUIRED",
        override: {
            apis: (oI) => {
                return {
                    ...oI,
                    verifyEmailPOST: async function (input) {
                        let response = await oI.verifyEmailPOST!(input);
                        if (response.status === "OK") {
                            // This will update the email of the user to the one
                            // that was just marked as verified by the token.
                            await Passwordless.updateUser({
                                userId: response.user.id,
                                email: response.user.email,
                            });
                        }
                        return response;
                    },
                };
            },
        },
    }),
    Session.init(),
  ],
});

import (
    "github.com/supertokens/supertokens-golang/recipe/emailverification"
    "github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
    "github.com/supertokens/supertokens-golang/recipe/passwordless"
    "github.com/supertokens/supertokens-golang/recipe/passwordless/plessmodels"
    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    err := supertokens.Init(supertokens.TypeInput{
        AppInfo: supertokens.AppInfo{
            AppName:       "...",
            APIDomain:     "...",
            WebsiteDomain: "...",
        },
        RecipeList: []supertokens.Recipe{
            passwordless.Init(plessmodels.TypeInput{
                FlowType: "USER_INPUT_CODE_AND_MAGIC_LINK",
                ContactMethodEmailOrPhone: plessmodels.ContactMethodEmailOrPhoneConfig{
                    Enabled: true,
                },
            }),
            emailverification.Init(evmodels.TypeInput{
                Mode: evmodels.ModeRequired,
                Override: &evmodels.OverrideStruct{
                    APIs: func(originalImplementation evmodels.APIInterface) evmodels.APIInterface {

                        originalVerifyEmailPOST := *originalImplementation.VerifyEmailPOST

                        (*originalImplementation.VerifyEmailPOST) = func(token string, sessionContainer sessmodels.SessionContainer, options evmodels.APIOptions, userContext supertokens.UserContext) (evmodels.VerifyEmailPOSTResponse, error) {
                            response, err := originalVerifyEmailPOST(token, sessionContainer, options, userContext)
                            if response.OK != nil {
                                // This will update the email of the user to the one
                                // that was just marked as verified by the token.
                                _, err := passwordless.UpdateUser(response.OK.User.ID, &response.OK.User.Email, nil)
                                if err != nil {
                                    // TODO: Handle error
                                }
                            }

                            return response, err
                        }

                        return originalImplementation
                    },
                },
            }),
            session.Init(nil),
        },
    })

    if err != nil {
        panic(err.Error())
    }
}


from supertokens_python import init, InputAppInfo, SupertokensConfig
from supertokens_python.recipe import passwordless, emailverification
from supertokens_python.recipe.emailverification.interfaces import (
    APIInterface,
    APIOptions
)

from supertokens_python.recipe.passwordless.asyncio import (
    update_user
)

from supertokens_python.recipe.passwordless import ContactEmailOrPhoneConfig

from supertokens_python.recipe.emailverification.interfaces import (
    EmailVerifyPostOkResult
)

from supertokens_python.recipe.session.interfaces import (
    SessionContainer
)
from supertokens_python import (
    InputAppInfo,
    SupertokensConfig,
)

from typing import Optional, Dict, Any


def override_email_verification_apis(original_implementation: APIInterface):
    original_email_verification_verify_email_post = original_implementation.email_verify_post
    
    async def email_verify_post(token: str, session: Optional[SessionContainer], api_options: APIOptions, user_context: Dict[str, Any] ):
        verification_response = await original_email_verification_verify_email_post(token, session, api_options, user_context)
        
        if isinstance(verification_response, EmailVerifyPostOkResult):
            await update_user(verification_response.user.user_id, verification_response.user.email)
        
        return verification_response
    
    original_implementation.email_verify_post = email_verify_post
    return original_implementation


init(
    supertokens_config=SupertokensConfig(
        connection_uri="..."
    ),
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    framework="flask",
    recipe_list=[
        passwordless.init(
            flow_type="USER_INPUT_CODE_AND_MAGIC_LINK",
            contact_config=ContactEmailOrPhoneConfig()
            ),
        emailverification.init(
        "REQUIRED",
        override=emailverification.InputOverrideConfig(
            apis=override_email_verification_apis
        ),
    ),
    ],
)

Auth Methods

Add ons

Allow users to change their email

caution

Flow 1: Update email without verifying the new email.#

Step 1: Creating the `/change-email` route#

Important

Step 2: Validate the new email and update the account#

Important

Flow 2: Updating email after verifying the new email.#

Step 1: Creating the `/change-email` route#

Important

Step 2: Validate the email and initiate the email verification flow#

Important

Step 3: Override the `verifyEmailPost` API to update the user's account on successful email verification#

Important

caution

Flow 1: Update email without verifying the new email.#

Step 1: Creating the /change-email route#

Important

Step 2: Validate the new email and update the account#

Important

Flow 2: Updating email after verifying the new email.#

Step 1: Creating the /change-email route#

Important

Step 2: Validate the email and initiate the email verification flow#

Important

Step 3: Override the verifyEmailPost API to update the user's account on successful email verification#

Important

Step 1: Creating the `/change-email` route#

Step 1: Creating the `/change-email` route#

Step 3: Override the `verifyEmailPost` API to update the user's account on successful email verification#