SuperTokens Rownd User Migration Plugin

This plugin facilitates the migration of users and sessions from Rownd to SuperTokens.

Installation

npm install @supertokens-plugins/rownd-nodejs

Quick Start

Backend Configuration

Initialize the plugin in your SuperTokens backend configuration.

[!IMPORTANT] This plugin requires the Session and UserMetadata recipes to be initialized in your SuperTokens configuration.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import UserMetadata from "supertokens-node/recipe/usermetadata";
import RowndMigrationPlugin from "@supertokens-plugins/rownd-nodejs";

SuperTokens.init({
  appInfo: {
    // your app info
  },
  recipeList: [
    Session.init(),
    UserMetadata.init(),
    // your other recipes
  ],
  experimental: {
    plugins: [
      RowndMigrationPlugin.init({
        rowndAppKey: process.env.ROWND_APP_KEY,
        rowndAppSecret: process.env.ROWND_APP_SECRET,
        enableDebugLogs: process.env.ENABLE_DEBUG_LOGS === "true",
      }),
    ],
  },
});

API Endpoint

The plugin exposes a single endpoint:

[!IMPORTANT] The plugin always migrates users and sessions into the public tenant. Rownd users with multiple supported login methods are rejected unless SuperTokens account linking is enabled in the target environment.

Migrate

• POST /plugin/rownd/migrate
• Headers: Authorization: Bearer <Rownd_JWT>
• Description: Validates the Rownd JWT, ensures the user is migrated to SuperTokens in the public tenant, syncs Rownd user data to SuperTokens UserMetadata, and then creates a new SuperTokens session for that user.

Debug Logging

Set enableDebugLogs: true in the plugin config to enable debug logging.

Telemetry

Telemetry is optional. If telemetry is omitted from the plugin config, no telemetry is emitted.

The plugin emits exactly one telemetry event per /migrate call result.

Event shape

Each event includes endpoint outcome data only (not step-by-step events), including:

• operation: migrate
• outcome: success or error
• durationMs
• tenantId (when available)
• rowndUserId (when available)
• superTokensUserId (when available)
• migrationState: already-migrated or imported-during-request (when available)
• for errors: error.message and error.name

[!NOTE] Telemetry failures never fail migration endpoints. Errors in telemetry reporting are swallowed.

Provider: OpenTelemetry

RowndMigrationPlugin.init({
  rowndAppKey: process.env.ROWND_APP_KEY,
  rowndAppSecret: process.env.ROWND_APP_SECRET,
  telemetry: {
    provider: "opentelemetry",
  },
});

[!IMPORTANT] This plugin uses @opentelemetry/api only. You still need to initialize OpenTelemetry SDK/exporters in your app for spans to be exported.

Provider: Axiom

RowndMigrationPlugin.init({
  rowndAppKey: process.env.ROWND_APP_KEY,
  rowndAppSecret: process.env.ROWND_APP_SECRET,
  telemetry: {
    provider: "axiom",
    token: process.env.AXIOM_TOKEN!,
    dataset: process.env.AXIOM_DATASET!,
    // optional, defaults to https://api.axiom.co/v1/datasets
    // url: "https://api.axiom.co/v1/datasets",
  },
});

Provider: Custom

RowndMigrationPlugin.init({
  rowndAppKey: process.env.ROWND_APP_KEY,
  rowndAppSecret: process.env.ROWND_APP_SECRET,
  telemetry: {
    provider: "custom",
    factory: () => ({
      recordEvent: async (event) => {
        // send to your telemetry backend
      },
    }),
  },
});

Bulk Import Script

The package includes a bulk migration script for importing Rownd users into SuperTokens.

The script now runs directly from a YAML config file that lives beside the script:

• config file: packages/rownd-nodejs/scripts/config.yaml
• script: packages/rownd-nodejs/scripts/bulkMigrate.ts

Usage

1. Edit scripts/config.yaml with your Rownd and SuperTokens credentials.
2. Run the script from packages/rownd-nodejs.

npm run bulk-import

The script:

• fetches users from Rownd page by page
• validates the Rownd payload shape with zod
• maps users with mapRowndUserToSuperTokens
• imports them into SuperTokens in bounded batches
• writes a checkpoint file so the run can resume later

Config File

All runtime config is read from scripts/config.yaml. There is no environment variable parsing.