Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Assigning custom user IDs

This feature allows you to change the default SuperTokens user ID (UUID v4) to a value that you prefer. There are two primary use cases for this:

  • Use case 1: During migration of users
  • Use case 2: If you prefer a different user ID format than the default one.

The way this feature works is that SuperTokens will store and manage the user ID mapping in the SuperTokens core. So when that users logs in, you will get back the mapped (the custom) user ID instead of the SuperTokens user ID.

Features like user roles, user metadata, session will also all work based on the custom user ID.

Use case 1: Migration of users#

This topic is better covered under the migration section. The main purpose of this is that you can retain the existing user IDs of your users when migrating them to SuperTokens. This makes it easier to migrate users without having to update the user IDs in your database.

Use case 2: If you prefer a different user ID format than the default one.#

You can call the user ID mapping function post sign up as shown below. It is important to know that user ID mapping can only be done, before there is any other data (session, roles etc) associated with the user.

import SuperTokens from "supertokens-node";
import ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import Session from "supertokens-node/recipe/session";
import { RecipeUserId } from "supertokens-node";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        EmailPassword.init({
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,

                        // override the email password sign up function
                        signUp: async function (input) {
                            let response = await originalImplementation.signUp(input);

                            if (response.status === "OK" && response.user.loginMethods.length === 1 && input.session === undefined) {
                                let externalUserId = "<CUSTOM USER ID>"
                                await SuperTokens.createUserIdMapping({ superTokensUserId: response.user.id, externalUserId })
                                
                                // we modify the response object to have the custom user ID.
                                response.user.id = externalUserId
                                response.user.loginMethods[0].recipeUserId = new RecipeUserId(externalUserId);
                                response.recipeUserId = new RecipeUserId(externalUserId);
                            }

                            return response;
                        },
                    }
                }
            }
        }),
        ThirdParty.init({
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,

                        // override the thirdparty sign in / up function
                        signInUp: async function (input) {
                            let response = await originalImplementation.signInUp(input);

                            if (response.status === "OK") {
                                if (response.createdNewRecipeUser && response.user.loginMethods.length === 1 && input.session === undefined) {
                                    let externalUserId = "<CUSTOM USER ID>"
                                    await SuperTokens.createUserIdMapping({ superTokensUserId: response.user.id, externalUserId })
                                    
                                    // we modify the response object to have the custom user ID.
                                    response.user.id = externalUserId
                                    response.user.loginMethods[0].recipeUserId = new RecipeUserId(externalUserId);
                                    response.recipeUserId = new RecipeUserId(externalUserId);
                                }
                            }

                            return response;
                        }
                    }
                }
            }
        }),
        Session.init({ /* ... */ })
    ]
});
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI