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 Passwordless from "supertokens-node/recipe/passwordless"
import Session from "supertokens-node/recipe/session";
import { RecipeUserId } from "supertokens-node";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        ThirdParty.init({
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        // override the thirdparty sign in / up API
                        signInUp: async function (input) {

                            let response = await originalImplementation.signInUp(input);

                            if (response.status === "OK") {
                                let { id, emails } = response.user;

                                // This is the response from the OAuth 2 provider that contains their tokens or user info.
                                let providerAccessToken = response.oAuthTokens["access_token"];
                                let firstName = response.rawUserInfoFromProvider.fromUserInfoAPI!["first_name"];

                                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;
                        },
                    }
                }
            }
        }),
        Passwordless.init({
            contactMethod: "EMAIL", // This example will work with any contactMethod
            flowType: "USER_INPUT_CODE_AND_MAGIC_LINK", // This example will work with any flowType

            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        consumeCode: async (input) => {
                            // First we call the original implementation of consumeCode.
                            const response = await originalImplementation.consumeCode(input);

                            // Post sign up response, we check if it was successful
                            if (response.status === "OK") {
                                if ("phoneNumber" in response.user) {
                                    const { id, phoneNumbers } = response.user;
                                } else {
                                    const { id, emails } = response.user;
                                }

                                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