Stytch Migration Guide

This guide covers a full migration, where Descope becomes the identity provider and source of truth for users, organizations, sessions, and machine identities. A complete migration includes four connected parts:

• Identity data - Consumer Users, B2B Organizations and Members, profile attributes, roles, and permissions.
• Application integration - Stytch UI and SDKs, protected routes, session validation, refresh, and logout.
• B2B configuration - Organization-specific authentication settings, SSO, SCIM, and member authorization.
• Machine identities - M2M clients, client credentials, scopes, token audiences, and secret rotation.

You can roll out the migration in phases, but every Stytch dependency must be migrated before you retire the Stytch project and credentials.

Stytch and Descope Concepts

Full Migration

Prerequisites

Before exporting data, ensure you have:

• A Stytch Project ID and secret with access to the Consumer or B2B resources you need to export.
• An inventory of every Stytch environment and whether it uses Consumer Auth, B2B Auth, or both.
• An inventory of authentication methods, Organizations, Members, RBAC settings, SSO connections, SCIM directories, M2M clients, webhooks, and application code that reads Stytch IDs or token claims.
• A non-production Descope project for testing, plus its Project ID.
• A Descope Management Key. Keep it on the server and never expose it to a browser or mobile application.
• A cutover and rollback plan, including how you will handle writes that occur between the initial export and cutover.

1. Export Data from Stytch

Stytch uses different export APIs for Consumer and B2B projects. All three Search APIs use cursor pagination. Request up to 1,000 records per page, save each response, and continue with results_metadata.next_cursor until it is empty.

Choose the API host that matches your Stytch credentials:

Using Test credentials against the Live host, or Live credentials against the Test host, returns a project_not_found error even when the credentials themselves are valid.

Consumer Auth

Use the Stytch Search Users endpoint to export all Consumer Users:

curl --request POST \
  --url "${STYTCH_API_URL}/v1/users/search" \
  --user "${STYTCH_PROJECT_ID}:${STYTCH_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"limit":1000}'

Export each User's login identifiers, verification state, name, status, roles, metadata, authentication registrations, and original user_id. Stytch also provides a linked user export utility for writing Consumer Users to CSV or JSON.

B2B Auth

Export Organizations before Members because every Member and tenant-scoped role depends on the Organization mapping.

The Search APIs have different rate limits. Stytch currently documents 150 requests per minute for Consumer Users, 100 requests per second for Organizations, and 100 requests per minute for Members. Process 429 responses with backoff and use the current endpoint documentation as the source of truth when you run the export.

Password Migration

Stytch's Search APIs do not export password hashes. Request a password hash export from Stytch Support and verify that its algorithm and parameters match Descope's supported password formats. If a compatible hash export is unavailable, use one of these options, both of which can be handled through Descope Flows.

1. Require Password Reset on First Login You can configure a Flow to prompt users to reset their password the first time they sign in through Descope. After resetting, users will authenticate using their newly set password for future logins. Learn more on our Flows page.

2. Move to Passwordless Authentication Alternatively, you can adopt a fully passwordless approach. Descope supports a variety of passwordless authentication methods. Explore them on our Authentication Methods page.

2. Map Stytch Data to Descope

Create a durable mapping file for every Stytch ID used by your application. Preserve it until application records, webhooks, SSO/SCIM configuration, and operational tools no longer depend on the legacy IDs.

Stytch Members are scoped to Organizations, while Descope Users are project-level. If the same verified email represents one person in multiple Stytch Organizations, create one Descope User and aggregate all tenant memberships in userTenants. Do not merge records solely because their email strings match: first resolve conflicting profile data, verification state, status, or evidence that the records represent different people.

Example transformed B2B user:

{
  "loginIds": ["ada@example.com"],
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "verifiedEmail": true,
  "status": "enabled",
  "userTenants": [
    {
      "tenantId": "organization-live-acme",
      "roleNames": ["admin"]
    }
  ],
  "customAttributes": {
    "freshlyMigrated": true
  }
}

The optional freshlyMigrated attribute lets a Descope Flow route migrated users through password reset, contact verification, or authenticator re-enrollment and clear the flag when the migration journey is complete.

3. Import into Descope

Test the transformation with representative Consumer Users, single-tenant Members, multi-tenant Members, and disabled or invited records in a non-production project. Then import dependencies in this order:

1. Permissions - Create the permission names your application checks. See RBAC with SDKs.
2. Tenants - Create one tenant for each mapped Stytch Organization. See Tenant Management.
3. Roles - Create project-level Consumer roles and tenant-level Organization roles after their permissions and tenants exist.
4. Users and memberships - Use the Batch Create Users API or the Management SDK's createBatch method. Include all mapped tenant IDs and tenant-scoped role names in userTenants.

Use createBatch, not an invitation operation, so the bulk load does not send unexpected invitation emails. Batch requests can partially succeed, so save and inspect createdUsers, failedUsers, and additionalErrors after every request. Correct the underlying data and retry only failed records.

See the user JSON formatting guide for Console imports. Use the API or Management SDK when you need to preserve tenant memberships, roles, password hashes, or precise status values.

4. Cut Over

1. Freeze relevant writes in Stytch or keep both systems synchronized during the final migration window.
2. Run a delta export for users, Organizations, Members, roles, and profile changes made after the initial export.
3. Import and verify the delta, then switch the application and API services to Descope.
4. Keep Stytch available for rollback until the post-migration checks pass.
5. Disable Stytch sign-up and authentication only after traffic, audit events, and support signals confirm the cutover.

Existing Stytch sessions are not imported into Descope. A full cutover normally requires users to sign in once through Descope. If you need a phased transition, use the Session Migration guide to design dual-token validation or session handoff before switching all traffic.

Replace Stytch SDKs

SDK and Configuration Mapping

Replace each Stytch surface with the Descope SDK for the same application layer:

Inventory and replace imports, environment variables, callback routes, cookie readers, session middleware, user/member lookups, Organization switching, authorization checks, logout handlers, and webhook verification before removing Stytch packages.

Next.js Example

For a Next.js application, replace the Stytch packages with the Descope SDK:

npm uninstall @stytch/nextjs stytch
npm install @descope/nextjs-sdk

Wrap the application with AuthProvider, then render the migrated authentication journey as a Descope Flow:

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider projectId={process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID!}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </AuthProvider>
  );
}

'use client';

import { Descope } from '@descope/nextjs-sdk';
import { useRouter } from 'next/navigation';

export default function SignInPage() {
  const router = useRouter();

  return <Descope flowId="sign-up-or-in" onSuccess={() => router.replace('/dashboard')} />;
}

Configure authentication methods, branding, MFA, and conditional logic in the Flow Builder, rather than recreating each Stytch frontend authentication call in application code.

Protect routes with authMiddleware() and preserve the same public-route allowlist used by the Stytch integration:

import { authMiddleware } from '@descope/nextjs-sdk/server';

export default authMiddleware({
  projectId: process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID,
  redirectUrl: '/sign-in',
  publicRoutes: ['/', '/sign-in'],
});

export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

Use session() in App Router Server Components and route handlers:

import { session } from '@descope/nextjs-sdk/server';

export default async function DashboardPage() {
  const currentSession = await session();

  if (!currentSession) {
    return <p>Access denied</p>;
  }

  return <p>Signed in as {currentSession.token.sub}</p>;
}

Use useSession() and useUser() for client state, and use the SDK's logout helper so the refresh token is revoked:

'use client';

import { useDescope, useSession, useUser } from '@descope/nextjs-sdk/client';

export function UserMenu() {
  const sdk = useDescope();
  const { isAuthenticated, isSessionLoading } = useSession();
  const { user, isUserLoading } = useUser();

  if (isSessionLoading || isUserLoading) return <p>Loading...</p>;
  if (!isAuthenticated) return null;

  return (
    <div>
      <p>{user?.name ?? user?.email}</p>
      <button onClick={() => sdk.logout()}>Log out</button>
    </div>
  );
}

See the Next.js SDK guide for Pages Router session access and additional integration options.

Session and Claim Differences

Stytch's session_token is opaque and its session_jwt is a signed representation of the same underlying Session. Descope instead issues a signed session JWT and a refresh JWT. In Next.js, the SDK stores these in DS and DSR cookies by default and validates the session through authMiddleware() or session().

Account for these differences when replacing Stytch session code:

• User identity - Read the user ID from sub. Use useUser() or a user-management call for profile data.
• Tenant context - Replace request-time organization_id reads with dct for the active tenant and tenants for all memberships and tenant-scoped roles or permissions.
• Profile claims - Descope session JWTs do not include fields such as email, name, or picture by default. Read them from the User object or add the required claims with a JWT Template.
• Audience - If an API currently validates Stytch's aud claim, add the intended audience to the JWT Template and pass the expected audience to the backend SDK's session-validation method.
• Refresh - Use the client SDK's refresh() helper when profile, role, or tenant changes must appear immediately; otherwise the next automatic refresh obtains current claims.
• Logout - Client SDK logout handles revocation and local state. For backend-managed logout, revoke the refresh token and clear both session and refresh cookies.

Migrate M2M Clients

Stytch M2M clients use the OAuth 2.0 client credentials grant and issue access tokens containing a client subject, scopes, an audience, expiration, and optional custom claims. Preserve that OAuth model with Descope Resources, confidential Inbound Apps, and Policies:

1. Create a Resource for each protected API. Use its identifier as the token audience and define the API's scope catalog.
2. Create a confidential Inbound App for each Stytch M2M client and store its new client secret securely.
3. Create a Policy that grants the Inbound App the required scopes on the Resource through the client_credentials grant.
4. Configure an Inbound App JWT Template for any required custom claims.
5. Update the service to request tokens from Descope and update receiving APIs to validate the Descope issuer, JWKS, audience, expiration, and scopes.

Follow the Inbound Apps client credentials guide for the token endpoint and request format. During cutover, issue the new credentials, update one service at a time, temporarily accept both issuers where necessary, and revoke each Stytch M2M client only after its traffic has moved to Descope.

Additional Stytch Features

Post-Migration Verification

Data and Authorization

• Compare exported and imported Consumer User counts, and resolve every failed or skipped record.
• Compare Stytch Organization counts with Descope Tenant counts and review the ID mapping file.
• Compare Member counts and verify representative single-tenant and multi-tenant users have every expected userTenants association.
• Review pending, invited, disabled, deleted, and locked records against the migration policy.
• Confirm verified email and phone flags were preserved without promoting unverified identifiers.
• Confirm project-level and tenant-level roles, permissions, and application authorization checks match Stytch behavior.
• Verify legacy Stytch IDs and required metadata remain available in the mapping file or approved custom attributes.

Authentication and Application Integration

• Test every enabled login method, including password reset or passwordless fallback and required factor re-enrollment.
• Confirm protected routes reject unauthenticated requests while intended public routes remain public.
• Verify session and refresh tokens are created, refreshed, revoked, and cleared correctly on logout.
• Confirm APIs reject expired, invalid, and wrong-issuer tokens.
• Confirm sub, dct, tenants, roles, permissions, custom profile claims, and aud are present where required.
• Test tenant discovery and switching for users with one, multiple, and no tenant memberships.
• Search source files, dependency manifests, environment configuration, deployment configuration, and tests for stale Stytch imports, credentials, hosts, callback routes, cookie names, and claim reads.

M2M and Enterprise Features

• Request a Descope client-credentials token for every migrated M2M service and validate its issuer, subject, audience, scopes, expiration, and custom claims.
• Confirm each API rejects a client that lacks the required Policy or scope.
• Test secret rotation and verify services no longer send Stytch M2M credentials before revoking them.
• Test every migrated SAML/OIDC connection, domain-routing rule, attribute mapping, and group-to-role mapping.
• Test SCIM user create, update, deactivate, group membership, and role mapping from each connected directory.
• Confirm audit events and external webhook delivery cover required authentication, administration, and provisioning actions.