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.
/change-email
route#
Step 1: Creating the - 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
Important
For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.
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
Important
For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.
// the following example uses express
import EmailPassword from "supertokens-node/recipe/emailpassword";
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 EmailPassword.updateEmailOrPassword({
recipeUserId: session.getRecipeUserId(),
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
}
if (resp.status === "EMAIL_CHANGE_NOT_ALLOWED_ERROR") {
// This is possible if you have enabled account linking.
// See our docs for account linking to know more about this.
// TODO: tell the user to contact support.
}
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/emailpassword"
"github.com/supertokens/supertokens-golang/recipe/session"
)
type RequestBody struct {
Email string
}
// the following example uses net/http
func test() {
_ = 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 := emailpassword.UpdateEmailOrPassword(userId, &requestBody.Email, nil, nil, 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.emailpassword.syncio import update_email_or_password
from supertokens_python.recipe.emailpassword.interfaces import (
UpdateEmailOrPasswordOkResult,
UpdateEmailOrPasswordEmailChangeNotAllowedError,
EmailAlreadyExistsError,
)
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()
email = str(request_body["email"])
if request_body is None:
# handle invalid request body error
return
# validate the input email
if not is_valid_email(email):
# TODO: handle invalid email error
return
# update the users email
update_response = update_email_or_password(
session.get_recipe_user_id(), email=email
)
if isinstance(update_response, UpdateEmailOrPasswordOkResult):
# TODO send successful email update response
return
if isinstance(update_response, EmailAlreadyExistsError):
# TODO handle error, email already exists
return
if isinstance(update_response, UpdateEmailOrPasswordEmailChangeNotAllowedError):
# This is possible if you have enabled account linking.
# See our docs for account linking to know more about this.
# TODO: tell the user to contact support.
return
raise Exception("Should never reach here")
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.
/change-email
route#
Step 1: Creating the - 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
Important
For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.
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
Important
For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.
// the following example uses express
import EmailPassword from "supertokens-node/recipe/emailpassword";
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";
import supertokens from "supertokens-node";
import {isEmailChangeAllowed} from "supertokens-node/recipe/accountlinking"
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");
}
// 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.getRecipeUserId(), email);
if (!isVerified) {
if (!(await isEmailChangeAllowed(session.getRecipeUserId(), email, false))) {
// this can come here if you have enabled the account linking feature, and
// if there is a security risk in changing this user's email.
return res.status(400).send("Email change not allowed. Please contact support");
}
// Before sending a verification email, we check if the email is already
// being used by another user. If it is, we throw an error.
let user = (await supertokens.getUser(session.getUserId()))!;
for (let i = 0; i < user.tenantIds.length; i++) {
let usersWithSameEmail = await supertokens.listUsersByAccountInfo(user.tenantIds[i], {
email
});
for (let y = 0; y < usersWithSameEmail.length; y++) {
// Since one user can be shared across many tenants, we need to check if
// the email already exists in any of the tenants that belongs to this user.
let currUser = usersWithSameEmail[y];
if (currUser?.id !== session.getUserId()) {
// TODO handle error, email already exists with another user.
return
}
}
}
// Now we create and send the email verification link to the user for the new email.
await EmailVerification.sendEmailVerificationEmail(session.getTenantId(), session.getUserId(), session.getRecipeUserId(), email);
// TODO send successful response that email verification email sent.
return
}
// Since the email is verified, we try and do an update
let resp = await EmailPassword.updateEmailOrPassword({
recipeUserId: session.getRecipeUserId(),
email: email,
});
if (resp.status === "OK") {
// TODO send successful response that email updated.
return
}
if (resp.status === "EMAIL_ALREADY_EXISTS_ERROR") {
// 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/recipe/emailpassword"
"github.com/supertokens/supertokens-golang/recipe/emailverification"
"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()
// 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 {
// Before sending a verification email, we check if the email is already
// being used by another user. If it is, we throw an error.
user, err := emailpassword.GetUserByID(sessionContainer.GetUserID())
if err != nil {
// TODO: handle error
}
if user != nil {
for i := 0; i < len(user.TenantIds); i++ {
// Since once user can be shared across many tenants, we need to check if
// the email already exists in any of the tenants.
userWithEmail, err := emailpassword.GetUserByEmail(user.TenantIds[i], requestBody.Email)
if err != nil {
// TODO: handle error
}
if userWithEmail != nil && userWithEmail.ID != sessionContainer.GetUserID() {
// TODO handle error, email already exists with another user.
return
}
}
}
// Now we create and send the email verification link to the user for the new email.
_, err = emailverification.SendEmailVerificationEmail(sessionContainer.GetTenantId(), userId, &requestBody.Email)
if err != nil {
// TODO: handle error
}
// TODO send successful response that email verification email sent.
return
}
// Since the email is verified, we try and do an update
updateResponse, err := emailpassword.UpdateEmailOrPassword(userId, &requestBody.Email, nil, nil, 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, 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.emailpassword.syncio import (
update_email_or_password,
)
from supertokens_python.recipe.emailpassword.interfaces import (
UpdateEmailOrPasswordOkResult,
EmailAlreadyExistsError,
)
from supertokens_python.syncio import get_user, list_users_by_account_info
from supertokens_python.types import AccountInfo
from supertokens_python.recipe.emailverification.syncio import (
is_email_verified,
send_email_verification_email,
)
from flask import g, request, Flask
from re import fullmatch
from supertokens_python.recipe.accountlinking.syncio import is_email_change_allowed
app = Flask(__name__)
@app.route("/change-email", methods=["POST"])
@verify_session()
def change_email():
session: SessionContainer = g.supertokens
request_body = request.get_json()
if request_body is None:
# handle invalid request body error
return
# validate the input email
if not is_valid_email(request_body["email"]):
# TODO: handle invalid email error
return
user_id = session.get_user_id()
# 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(session.get_recipe_user_id(), request_body["email"])
if not is_verified:
if not is_email_change_allowed(
session.get_recipe_user_id(), request_body["email"], False
):
# Email change is not allowed, send a 400 error
return {"error": "Email change not allowed"}, 400
# Before sending a verification email, we check if the email is already
# being used by another user. If it is, we throw an error.
user = get_user(user_id)
if user is not None:
for tenant_id in user.tenant_ids:
users_with_same_email = list_users_by_account_info(
tenant_id, AccountInfo(email=request_body["email"])
)
for curr_user in users_with_same_email:
# Since one user can be shared across many tenants, we need to check if
# the email already exists in any of the tenants that belongs to this user.
if curr_user.id != user_id:
# TODO handle error, email already exists with another user.
return
# Create and send the email verification link to the user for the new email.
send_email_verification_email(
session.get_tenant_id(),
user_id,
session.get_recipe_user_id(),
request_body["email"],
)
# TODO send successful email verification response
return
# update the users email
update_response = update_email_or_password(
session.get_recipe_user_id(), email=request_body["email"]
)
if isinstance(update_response, UpdateEmailOrPasswordOkResult):
# TODO send successful email update response
return
if isinstance(update_response, EmailAlreadyExistsError):
# TODO handle error, email already exists
return
raise Exception("Should never reach here")
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
)
Multi Tenancy
- Notice that we loop through all the tenants that this user belongs to check that for each of the tenants, there is no other user with the new email. If we did not do this, then calling
updateEmailOrPassword
would fail because the email is already used by another user in one of the tenants that this user belongs to. So in that case, we do not want to go through the verification process either. - We also pass in the tenantId of the current session when calling the
sendEmailVerificationEmail
function, so that the link generated will open the the tenant's UI that the user is currently interacting with. - When calling
updateEmailOrPassword
, it will returnEMAIL_ALREADY_EXISTS_ERROR
if the new email exists in any of the tenants that the user ID is a part of.
verifyEmailPost
API to update the user's account on successful email verification#
Step 3: Override the - Update the accounts email on successful email verification.
- NodeJS
- GoLang
- Python
- Other Frameworks
Important
For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.
import SuperTokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";
import EmailVerification from "supertokens-node/recipe/emailverification";
import Session from "supertokens-node/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
},
recipeList: [
EmailPassword.init(),
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 EmailPassword.updateEmailOrPassword({
recipeUserId: response.user.recipeUserId,
email: response.user.email,
});
}
return response;
},
};
},
},
}),
Session.init(),
],
});
import (
"github.com/supertokens/supertokens-golang/recipe/emailpassword"
"github.com/supertokens/supertokens-golang/recipe/emailverification"
"github.com/supertokens/supertokens-golang/recipe/emailverification/evmodels"
"github.com/supertokens/supertokens-golang/recipe/session"
"github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
"github.com/supertokens/supertokens-golang/supertokens"
)
func test() {
err := supertokens.Init(supertokens.TypeInput{
AppInfo: supertokens.AppInfo{
AppName: "...",
APIDomain: "...",
WebsiteDomain: "...",
},
RecipeList: []supertokens.Recipe{
emailpassword.Init(nil),
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, tenantId string, options evmodels.APIOptions, userContext supertokens.UserContext) (evmodels.VerifyEmailPOSTResponse, error) {
response, err := originalVerifyEmailPOST(token, sessionContainer, tenantId, 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 := emailpassword.UpdateEmailOrPassword(response.OK.User.ID, &response.OK.User.Email, nil, nil, &tenantId)
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 emailpassword, emailverification
from supertokens_python.recipe.emailverification.interfaces import (
APIInterface,
APIOptions,
)
from supertokens_python.recipe.emailpassword.asyncio import update_email_or_password
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],
tenant_id: str,
api_options: APIOptions,
user_context: Dict[str, Any],
):
verification_response = await original_email_verification_verify_email_post(
token, session, tenant_id, api_options, user_context
)
if isinstance(verification_response, EmailVerifyPostOkResult):
await update_email_or_password(
verification_response.user.recipe_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=[
emailpassword.init(),
emailverification.init(
"REQUIRED",
override=emailverification.InputOverrideConfig(
apis=override_email_verification_apis
),
),
],
)