Skip to main content

User management actions

Overview​

SuperTokens exposes a set of functions and APIs that you can use to have manual control over your users. Actions like fetching users or deleting them are available through different SDK calls.

Get user​

By email​

import supertokens from "supertokens-node";

async function getUserInfo() {
    let usersInfo = await supertokens.listUsersByAccountInfo("public", {
        email: "test@example.com"
    });

    /**
     * 
     * userInfo contains the following info:
     * - emails
     * - id
     * - timeJoined
     * - tenantIds
     * - phone numbers
     * - third party login info
     * - all the login methods associated with this user.
     * - information about if the user's email is verified or not.
     * 
    */
}
Multi Tenancy

Notice that the first argument of the above function is "public". This is the default tenantId, which means that SuperTokens returns information about the user whose email is "test@example.com" in the "public" tenant.

If you are using the multi-tenancy feature, you can pass in a different tenantId to get information about a user in a different tenant.

By phone number​

import supertokens from "supertokens-node";

async function handler() {
    let usersInfo = await supertokens.listUsersByAccountInfo("public", {
        phoneNumber: "+1234567890"
    });

    /**
     * 
     * userInfo contains the following info:
     * - emails
     * - id
     * - timeJoined
     * - tenantIds
     * - phone numbers
     * - third party login info
     * - all the login methods associated with this user.
     * - information about if the user's email is verified or not.
     * 
    */
}
Multi Tenancy

Notice that the "public" tenantId appears in the function call above. This is the default tenantId and returns the user with the given phone number that belongs to the public tenant. You can provide a different tenantId if required.

By User ID​

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

let app = express();
app.get("/get-user-info", verifySession(), async (req: SessionRequest, res) => {
    let userId = req.session!.getUserId();
    
    let userInfo = await supertokens.getUser(userId)

    /**
     * 
     * userInfo contains the following info:
     * - emails
     * - id
     * - timeJoined
     * - tenantIds
     * - phone numbers
     * - third party login info
     * - all the login methods associated with this user.
     * - information about if the user's email is verified or not.
     * 
    */
})
Tip

The authentication session also contains the user ID and the session payload. You can access it on both the backend and the frontend.

Using the user metadata recipe​

Checkout the user metadata recipe docs which shows you how to save and fetch any JSON object against the user's ID. You can use this to save information like the user's name (first_name and last_name) or any other field associated with the user.

Delete user​

import {deleteUser} from "supertokens-node";

async function deleteUserForId() {
    let userId = "..." // get the user ID
    await deleteUser(userId); // this will succeed even if the userId didn't exist.
}
caution
  • Calling this function permanently removes all information associated with this user, including their sessions.
  • If this user has an active access token, and you have not enabled access token blacklisting, session verification still succeeds until their access token expires. After that, the system logs them out since session refresh fails.

List users​

Newest first​

import { getUsersNewestFirst } from "supertokens-node";

async function getUsers() {
    // get the latest 100 users
    let usersResponse = await getUsersNewestFirst({
		tenantId: "public"
	});

    let users = usersResponse.users;
    let nextPaginationToken = usersResponse.nextPaginationToken;

    // get the next 200 users
    usersResponse = await getUsersNewestFirst({
		tenantId: "public",
        limit: 200,
        paginationToken: nextPaginationToken,
    })

    users = usersResponse.users;
    nextPaginationToken = usersResponse.nextPaginationToken;

    // get for specific recipes
    usersResponse = await getUsersNewestFirst({
		tenantId: "public",
        limit: 200,
        paginationToken: nextPaginationToken,
		// only get for those users who signed up with 
        includeRecipeIds: [""],
    })

    users = usersResponse.users;
    nextPaginationToken = usersResponse.nextPaginationToken;
}

Oldest first​

import { getUsersOldestFirst } from "supertokens-node";

async function getUsers() {
    // get the latest 100 users
    let usersResponse = await getUsersOldestFirst({
		tenantId: "public"
	});
    let users = usersResponse.users;
    let nextPaginationToken = usersResponse.nextPaginationToken;

    // get the next oldest 200 users
    usersResponse = await getUsersOldestFirst({
		tenantId: "public",
        limit: 200,
        paginationToken: nextPaginationToken,
    });

    users = usersResponse.users;
    nextPaginationToken = usersResponse.nextPaginationToken;

    // get for specific recipes
    usersResponse = await getUsersOldestFirst({
		tenantId: "public",
        limit: 200,
        paginationToken: nextPaginationToken,
        // only get for those users who signed up with 
        includeRecipeIds: [""]
    });

    users = usersResponse.users;
    nextPaginationToken = usersResponse.nextPaginationToken;
}
  • If the nextPaginationToken is undefined, then there are no more users to loop through.
  • If there are no users in your app, then nextPaginationToken is undefined and users is an empty array
  • Each element in the users array is according to the output of the core API as shown in the API documentation.
Multi Tenancy

Notice that the tenantId appears as "public". This means that the functions above loop through the users of the public tenantId. If you want to loop through other tenant IDs, you can pass in the tenant ID string to the function call.

This also implies that there is no way to loop through all users across all tenants in one go. If you want to do this, you must loop through each tenant one by one.

Count users​

import {getUserCount} from "supertokens-node";

async function getCount() {
    let count = await getUserCount()
}
Multi Tenancy

By default, the getUserCount function returns the number of users across all tenants. If you want to get the number of users for a specific tenant, you can pass in the tenant ID string to the function call.