User metadata

Overview

You can use the UserMetadata recipe to store your custom data about each user. This can be any arbitrary values that are JSON serializable. The following page shows you how to enable and use the feature.

Enable the UserMetadata recipe

import SuperTokens from "supertokens-node";
import UserMetadata from "supertokens-node/recipe/usermetadata";

SuperTokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        // Initialize other recipes as seen in the quick setup guide
        UserMetadata.init(),
    ]
});

Store data

important

Only root-level properties merge into the stored object. Nested objects and all lower-level properties replace the existing ones.

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

let app = express();

app.post("/updateinfo", verifySession(), async (req, res) => {
  const session = req.session;
  const userId = session.getUserId();

  await UserMetadata.updateUserMetadata(userId, { newKey: "data" });

  res.json({ message: "successfully updated user metadata" });
});

Multi Tenancy

User metadata that associates with a user shares across all tenants that that user is a part of. If instead, you want to store user metadata on a tenant level, you can add a custom key in the JSON like:

{
  "tenant1": {
    "someKey": "specific to teannt1"
  },
  "tenant2": {
    "someKey": "specific to teannt2"
  },
  "someKey": "common for all tenants"
}

and then read the appropriate key based on the tenantId.

Access data

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

let app = express();

app.post("/updateinfo", verifySession(), async (req, res) => {
  const session = req.session;
  const userId = session.getUserId();

  const { metadata } = await UserMetadata.getUserMetadata(userId);

  res.json({ preferences: metadata.preferences });
});

Important

By default, all users have an empty metadata object.

Delete metadata

You can either delete all the user's metadata, or certain fields from them:

Delete specific fields

You can do this by calling the update metadata function and setting the field you want to remove to be null. For example, if you have the following metadata object for a user:

{
  "preferences": { "theme": "dark" },
  "notifications": { "email": true },
  "todos": ["use-text-notifs"]
}

And you want to remove the "notifications" field, you can update the metadata object with the following JSON:

{
  "notifications": null
}

This would result in the final metadata object:

{
  "preferences": { "theme": "dark" },
  "todos": ["use-text-notifs"]
}

Important

You can only remove the root level fields in the metadata object in this way. From the above example, if you set preferences.theme: null, then it does not remove the "theme" field, but instead sets it to a JSON null value.

In code, it would look like:

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

let app = express();

app.post("/updateinfo", verifySession(), async (req, res) => {
  const session = req.session;
  const userId = session.getUserId();

  await UserMetadata.updateUserMetadata(userId, { notifications: null });

  res.json({ message: "successfully updated user metadata" });
});

Delete the entire metadata object

Using this function deletes all the fields in the user metadata object for that user.

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

let app = express();

app.post("/updateinfo", verifySession(), async (req, res) => {
  const session = req.session;
  const userId = session!.getUserId();

  await UserMetadata.clearUserMetadata(userId);

  res.json({ success: true });
});

See also

Common User Management ActionsSession ManagementAllow Users to Update Their DataDashboard User Management