Stytch To Descope

Stytch → Descope Migration Skill

This skill guides self-service migrations from Stytch to Descope. It runs in three parts:

1. MCP Check — confirm whether the Descope MCP Server is available and suggest installing it if not
2. Migration Plan — gather context via triage questions, analyze the codebase's auth touchpoints, and produce a human-readable MIGRATION-PLAN.md for the user to review
3. Execution — if the user confirms they want to proceed, execute the plan

Do not collapse these parts or skip ahead. The plan must be reviewed before code changes begin. If the file view is truncated, partial, or cut off, continue reading with the appropriate offset until all lines have been loaded; do not proceed based on a partial read.

Stytch is not only an authentication provider — it is a broader identity platform spanning consumer authentication, multi-tenant/B2B authentication, organizations and members, enterprise SSO, SCIM, RBAC, JIT provisioning, MFA, session management, Admin Portal flows, fraud and risk protection, device fingerprinting, Protected Auth, machine-to-machine authentication, trusted auth tokens, and Connected Apps for OAuth/OIDC-based integrations and AI-agent access. A good migration first identifies which Stytch product surfaces are in use, then maps each one to the closest target feature or migration pattern. Expect Stytch migrations to vary more widely than a purely B2B auth migration, since a Stytch implementation may include consumer passwordless auth, enterprise-readiness features, fraud/risk infrastructure, and OAuth/OIDC connected-app workflows.

Primary references (both in this skill's directory):

• references/implementation-nuances.md — verified migration patterns for each framework, Stytch feature-to-Descope mappings, and known gotchas
• references/flows-and-widgets.md — Descope terminology/lingo, Flow structure and templates, Widgets, SSO Setup Suite, Console-vs-code decision guide

---

Guiding Principles

Console-first. Before recommending SDK code for any user-facing auth feature, check whether the Console, a Flow, a Widget, or the SSO Setup Suite covers the use case. Engineers integrate once (SDK setup + session validation). All subsequent auth evolution — new methods, MFA changes, UI updates, tenant SSO onboarding — should happen in the Console without code deployments. See references/flows-and-widgets.md → Console vs. Code.

Ask, don't assume. At any design decision point — Flow vs. custom code, Widget vs. custom page, MFA inline vs. separate enrollment, programmatic SSO vs. SSO Setup Suite, one-Organization-to-one-Tenant mapping — use AskUserQuestion rather than proceeding with an assumption. The cost of a wrong assumption compounds across 20+ files, and the Stytch Organization → Descope Tenant mapping in particular ripples into SSO, SCIM, RBAC, and domain routing. Uncertainty about architecture or intent is always worth a question.

MCP over memory. When the Descope MCP Server is available (confirmed in Part 1), use docs_ask_question to verify every SDK method name, option shape, and return type before writing it. Do not fall back to "verify the exact method name in the SDK type declarations" as a hedge — just verify it directly.

---

Part 1: MCP Check (BLOCKING)

Before doing anything else, check whether the Descope Docs MCP is available by calling search-descope-docs with a simple query (e.g., "session validation").

If the tool is available: proceed to Part 2 immediately.

If the tool is not available, show this message and use AskUserQuestion to ask whether they want to install it first:

> Descope Docs MCP is not installed. > > This skill uses the Descope Docs MCP to look up current API signatures, SDK methods, and > feature availability during migration. Without it, guidance is based on static training data, > which may be stale and can produce SDK calls that don't exist. > > You can install it in a few minutes at https://docs-mcp.descope.com/ (server URL: > https://docs-mcp.descope.com/mcp). It significantly improves the accuracy of the > migration output — especially for SDK lookups and flow-specific configuration. > > Would you like to install the MCP before we continue, or proceed without it?

• If they choose to install: pause and wait. Once they confirm it's installed, re-check by calling search-descope-docs again before proceeding.
• If they choose to proceed without it: continue, but flag any SDK-specific answers as "based on last known documentation — verify against the current SDK."

Do not proceed to Part 2 until this step is resolved.

---

Part 2: Migration Plan

Part 2 has two sub-steps:

1. Triage — ask the questions needed to understand scope (migration questions go here since answers shape the plan)
2. Codebase Analysis + Plan File — scan the project, produce MIGRATION-PLAN.md, and pause for review

Step 0: Triage (BLOCKING — requires AskUserQuestion)

Use the AskUserQuestion tool to gather the information below. Do not infer answers from memory, prior conversations, or assumptions — even if you think you know. The migration path differs based on these answers; getting them wrong wastes the user's time and produces incorrect guidance.

Do not proceed to Step 0.5 until the user has answered.

First AskUserQuestion call (up to 4 questions):

1. Backend language / framework — Present the most likely options based on any cues

in the conversation (e.g., Node.js, Go, Ruby, Python, Java). The user can always pick "Other."

1. Migration goal — Full cut-over, incremental/phased migration, or just evaluating.
2. Existing users and organizations — Are they migrating an app with active users and

organizations in Stytch, staging/dev only, or starting fresh? This determines whether user and organization migration planning is needed (user export, org-to-tenant mapping, SCIM continuity, phased vs. big-bang cutover, forced re-login on cutover).

Second AskUserQuestion call — Stytch feature usage (use multiSelect: true):

1. Which Stytch features are in use? Present the highest-impact categories:

• Consumer Authentication — which sign-in methods are enabled, such as OAuth/social login, email magic links, OTPs, passwords, passkeys, WebAuthn, mobile biometrics, MFA, TOTP, crypto wallet auth, or new-device notifications; whether the app uses Stytch UI, frontend SDKs, backend SDKs, or direct API calls.
• Multi-tenant / B2B Authentication — whether the Stytch B2B model is used; how Organizations and Members are modeled; whether members can belong to multiple organizations; whether org discovery, org-specific login, or organization switching/session exchange is used.
• Organizations and Members — organization metadata, member metadata, membership lifecycle, invitations, member search/update flows, deactivation behavior, and whether organization-specific auth policies are configured.
• Enterprise SSO — whether SAML, OIDC, or both are used; which identity providers are connected; whether setup is handled internally or by customer admins; whether SSO is organization-specific, multi-organization, or standalone; whether role assignment or JIT provisioning depends on SSO claims.
• SCIM — which workforce directories are connected; whether member provisioning, deprovisioning, group sync, group-to-role mapping, session revocation, or webhook handlers depend on SCIM behavior. Flag as high complexity.
• RBAC — how Stytch resources, actions, permissions, and roles are defined; whether roles are consumer-level or organization/member-level; where permission checks happen in code; whether roles or permissions are included in session tokens; whether SSO or SCIM maps groups/claims to roles.
• JIT Provisioning — which provisioning sources are allowed; whether users/members are automatically added to organizations after SSO, email-domain matching, discovery, invitations, or trusted token flows.
• MFA and Step-up Authentication — which second factors are used, such as SMS OTP, email OTP, TOTP, passkeys, WebAuthn, or other factors; whether MFA is globally required, organization-specific, risk-based, or used only for sensitive actions.
• Sessions and Tokens — how session tokens, session JWTs, intermediate sessions, custom claims, cookies, expiration, refresh, revocation, and frontend/backend session validation are implemented.
• Admin Portal UI — which customer-admin workflows are handled by Stytch today, such as member management, organization settings, SSO setup, SCIM setup, or RBAC management; whether the application generates Admin Portal links or embeds Stytch-provided admin flows.
• Fraud & Risk / Device Fingerprinting (including Protected Auth) — whether Device Fingerprinting is used for bot detection, credential stuffing protection, account takeover prevention, toll fraud prevention, free-trial abuse, remembered devices, trusted/unrecognized device detection, IP-geo restrictions, new-device notifications, or to enable Protected Auth mechanisms (which can block, challenge, add friction, or monitor suspicious attempts). Flag as high complexity if Stytch verdicts or Protected Auth flows influence authentication decisions or require custom enforcement logic.
• Connected Apps — whether the application uses Stytch to act as an OAuth/OIDC authorization server; which first-party, third-party, public, or confidential clients exist; which authorization code, PKCE, consent, token, refresh token, revocation, custom scope, or RBAC-backed scope flows are implemented. Flag as high complexity. First-party → Descope Federated Apps; third-party → Descope Inbound Apps (public vs. confidential applies only to Inbound Apps).
• AI Agent / MCP Authentication — whether Connected Apps are used for AI agents, MCP clients, CLI tools, external integrations, or agentic access to application data; review scopes, consent, dynamic client registration, token lifetimes, and organization-level controls before implementation. Flag for deeper review.
• Machine-to-Machine Authentication — whether M2M clients, client credentials, client secrets, JWT access tokens, scopes, custom claims, or secret rotation are used for service-to-service authentication.
• Trusted Auth Tokens — Stytch Trusted Auth Tokens let the application exchange an externally issued signed JWT for a Stytch

session. Stytch validates the JWT against a Trusted Auth Token Profile configured with issuer (iss), audience (aud), public keys or JWKS URL, and claim mappings. Flag as high complexity.

• Webhooks, Event Logs, and Event Streaming — which Stytch events are consumed by the application; whether event logs are shown to customers, streamed to external systems, used for compliance, or used to trigger internal user/org synchronization.
• The user can add others via “Other.”

After both calls, summarize findings and flag high-complexity items before proceeding to Step 0.5. The main high-complexity Stytch areas are typically SCIM, Enterprise SSO with JIT provisioning, RBAC tied to SSO or SCIM, Fraud & Risk/Device Fingerprinting, Protected Auth, Connected Apps, AI Agent/MCP authentication, Machine-to-Machine authentication, and Trusted Auth Tokens.

---

Step 0.5: Engineer Review Checkpoint (BLOCKING — requires AskUserQuestion)

These questions surface blockers the framework doesn't expose. Ask even the ones you think you know. Use AskUserQuestion before proceeding to codebase analysis.

Batch into calls of up to 4 questions. Skip questions that are clearly inapplicable given Step 0 answers (e.g., skip user migration planning if they said they're starting fresh).

Access and credentials

• Do they have access to the Descope Console and a Project ID? (If not, see Step 1.5.)
• Do they need a Management Key? Required for user CRUD, tenant management, RBAC, SSO/SCIM configuration, access keys, Inbound Apps, Outbound Apps, and other management operations.
• Do they have access to the Stytch Dashboard/API keys needed to inspect or export the current configuration, including Consumer Auth, B2B Organizations/Members, SSO, SCIM, RBAC, Connected Apps, Fraud & Risk, and Admin Portal settings?

Codebase scope

• Is this a Stytch Consumer Auth app, a Stytch Multi-tenant/B2B Auth app, or a hybrid app using both? This determines whether the migration centers on Users only or on Organizations/Members → Tenants/Users.
• Are there places in the app that read claims or session fields directly from Stytch tokens or session responses, such as user_id, member_id, organization_id, organization_slug, roles, permissions, trusted_metadata, untrusted_metadata, or custom claims? These need a Descope JWT Template or Flow Custom Claims configured before equivalent reads will work.
• Does the app read Stytch organization_id, member_id, sso_connection_id, scim_group_id, Connected App client IDs, or RBAC role_id / resource_id / action values in many places? The Stytch Organization → Descope Tenant remap ripples through SSO, SCIM, RBAC, JIT provisioning, Admin Portal replacement, Connected Apps, and membership checks — confirm the organization model before writing code.
• Are there multiple services or microservices validating Stytch session tokens, session JWTs, access tokens, or Connected Apps tokens? Each service needs to be updated to validate the correct Descope-issued JWTs or OAuth/OIDC tokens.
• Does the application use Stytch frontend SDK helpers, backend API calls, direct REST calls, Stytch UI components, or all of the above? This determines whether the migration is mostly Flow/UI replacement, backend SDK replacement, or both.
• Does the app depend on Stytch webhooks to keep its own database in sync? Search for webhook handlers before changing user, organization, member, SCIM, RBAC, fraud, or Connected Apps behavior.

Deployment and risk

• Do they have multiple environments (dev / staging / prod)? Each needs its own Descope project and Project ID, with matching redirect URLs, auth domains, SSO/SCIM configuration, Connected Apps, and environment-specific secrets.
• Is there a maintenance window, or does this need to be zero-downtime?
• Are any external customers, enterprise IdPs, SCIM directories, OAuth clients, MCP clients, or machine-to-machine clients already integrated with the Stytch production project? If yes, plan customer-facing cutover steps, not just code changes.
• Are login URLs, callback URLs, custom auth domains, email domains, OAuth issuer URLs, or JWKS URLs contractually or technically expected to stay stable? If yes, flag early because they affect SSO, sessions, Connected Apps, and token validation.

User, organization, and member migration (if they indicated existing users/orgs in Step 0)

• How many users, Organizations, and Members exist? This determines export approach and whether a phased cutover is warranted.
• Are they using Stytch Consumer Auth users, Stytch B2B Members, or both? Consumer users and B2B Members have different object shapes and should not be collapsed without confirming the target model.
• Do Stytch Members belong to multiple Organizations? If yes, preserve tenant membership and role assignment per organization when mapping to Descope Tenants.
• Do they use passwords in Stytch? Plan how password credentials carry over: import if supported, force reset, staged password migration, or replacement with passwordless methods. Verify the current Stytch export capability and Descope import path before committing to an approach.
• Which Stytch authentication methods are in use: OAuth/social login, OTP, magic links, passwords, passkeys/WebAuthn, mobile biometrics, TOTP, MFA, crypto wallets, or custom auth factors? Confirm migration feasibility for each method before writing implementation instructions.
• Big-bang cutover or phased? Map each Stytch Organization to a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: descope
• Source: descope/skills
• License: MIT

Install and usage instructions live in the source repository linked above.