Workos To Descope

WorkOS → Descope Migration Skill

This skill guides self-service migrations from WorkOS 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.

WorkOS is not only an authentication provider — it is a B2B/enterprise-readiness platform spanning authentication, organizations, enterprise SSO, SCIM/directory sync, RBAC, FGA, audit logs, connected accounts, admin setup flows, and security controls. A good migration first identifies which WorkOS features are in use, then maps each one to the closest Descope feature or migration pattern. Expect WorkOS migrations to be more B2B-enterprise heavy than a typical consumer-auth migration.

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

• references/implementation-nuances.md — verified migration patterns for each framework, WorkOS 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 — embed Flows vs. OIDC compatibility, 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 WorkOS 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 MCP Server is available by calling docs_search 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 MCP is not installed. > > This skill uses the Descope MCP server 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.descope.com/mcp/mcp-server (server URL: > https://mcp.descope.com). 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 docs_search 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). 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 WorkOS, 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 — WorkOS feature usage (use multiSelect: true):

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

• AuthKit — WorkOS's hosted/embeddable login UI and session management (email/password, social login, passkeys, MFA, magic auth); which sign-in methods are enabled and whether the hosted or embedded flow is used.
• Organizations — organization membership, organization switching, metadata, whether users can belong to multiple organizations.
• Enterprise SSO — connections SAML, OIDC, or both; whether setup is handled by internal engineers or by customer admins; whether domain-based SSO routing is used.
• Directory Sync / SCIM — which directories; group sync; group-to-role mapping; deprovisioning behavior; directory webhook handlers.
• Admin Portal / Widgets — which customer-admin workflows are hosted by WorkOS today; whether the app generates portal links; whether Descope Widgets or the SSO Setup Suite can replace them.
• RBAC — whether roles are global/environment or organization-scoped; where permission checks happen in code; whether roles/permissions are in tokens; whether IdP groups map to roles.
• FGA — the authorization model (resources, relationships, privileges, hierarchy); where checks are performed. Flag as high complexity.
• Audit Logs — whether logs are written to WorkOS, read back from WorkOS, shown to customers, or required for compliance.
• Radar — whether it blocks, challenges, or only notifies about suspicious auth attempts; custom rules.
• Pipes — which providers are connected; where connected-account tokens are used (AI agents, integrations, background jobs).
• Vault / Feature Flags — flag as potentially outside the core Descope identity migration.
• MCP Auth / Connect — flag for deeper review before implementation.
• The user can add others via "Other."

After both calls, summarize findings and flag high-complexity items (Directory Sync/SCIM, FGA, Pipes, MCP Auth/Connect, Vault) before proceeding to Step 0.5.

---

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, RBAC, ReBAC, tenant/SSO/SCIM configuration, Outbound Apps.)

Codebase scope

• Are there places in the app that read claims directly from the session token (e.g. user.email, claims.organization_id, role/permissions)? These need a JWT Template configured before they'll work.
• Does the app read WorkOS organizationId, connectionId, or directoryId in many places? The WorkOS Organization → Descope Tenant remap ripples through SSO, SCIM, RBAC, and membership checks — confirm the org model before writing code.
• Are there multiple services or microservices validating WorkOS tokens/sessions? Each needs to be updated to validate Descope JWTs.

Deployment and risk

• Do they have multiple environments (dev / staging / prod)? Each needs its own Descope project and Project ID.
• Is there a maintenance window, or does this need to be zero-downtime?

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

• How many users and organizations? This determines export approach and whether a phased cutover is warranted.
• Do they use passwords in AuthKit? Plan how password credentials carry over (export/import vs. reset vs. passwordless). Verify the current WorkOS user-export capability and the Descope import path before committing to an approach.
• Big-bang cutover or phased? Map each WorkOS Organization to a Descope Tenant first; user membership and tenant-scoped roles depend on it.
• SCIM is a lifecycle system, not a one-time import. If Directory Sync is enabled, enterprise directories will keep pushing create/update/suspend/delete events after cutover. A single user import is not enough — every SCIM/directory workflow must be re-pointed at Descope before cutover, or provisioning silently breaks.
• Are they aware that active WorkOS sessions will be invalidated on cutover unless a session-bridging approach is used? Plan for a forced re-login or phased rollout.

Gaps to flag immediately (don't ask — flag these proactively based on Step 0 answers)

• If they're using Vault or Feature Flags: these may have no direct Descope identity equivalent. Flag separately; do not pretend they are Descope SDK swaps. Ask whether they're in scope.
• If they're using MCP Auth / Connect: flag for deeper review before any implementation — likely maps to Descope Inbound Apps / OAuth app patterns, but needs dedicated mapping.
• If they're using Audit Logs: set up Descope's Audit Webhook Connector before cutover to avoid gaps in compliance/event logging. Missing this can break compliance visibility even though the app still runs.
• If they're using Pipes / connected accounts: connected third-party tokens may power integrations or background jobs. Identify provider connections and whether users must reconnect accounts.

Console/Flow/Widget opportunities (flag before codebase analysis, then ask):

• If the app uses the WorkOS Admin Portal or generates portal links: ask whether the SSO Setup Suite + Tenant Profile Widget replaces that workflow instead of rebuilding it as custom code. Do not default to building custom admin setup screens.
• If the app has a profile edit page or user management UI: ask whether a Descope Widget covers the use case.
• If the app has a separate MFA enrollment page: ask whether MFA should be integrated into the main sign-in Flow as a step or subflow instead (almost always cleaner in Descope).
• If any server-side code initiates SSO, generates emails, or runs logic during the auth journey: ask whether that logic can be a Flow step or Connector instead of server code.

Summarize any blockers and Console/Flow opportunities before proceeding to codebase analysis.

---

Step 1: Codebase Analysis

Scan the codebase to map every auth touchpoint before writing the plan.

Run these searches (adapt file extensions to the user's language):

# Find all WorkOS / AuthKit import sites.
grep -rni "workos\|authkit" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" \
  --include="*.mjs" --include="*.cjs" --include="*.py" --include="*.go" \
  --include="*.rb" --include="*.php" --include="*.java" --include="*.kt" \
  --include="*.cs" --include="*.ex" --include="*.exs" --include="*.rs" \
  --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=dist --exclude-dir=venv \
  . 2>/dev/null

# Find all WorkOS env var references
grep -rn "WORKOS_\|workos\." \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --include="*.env*" --include="*.yml" --include="*.yaml" --include="Dockerfile" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find WorkOS SDK surface + claim / token / org access patterns (things that may need a JWT Template or org→tenant remap)
grep -rn "workos.userManagement\|workos.organizations\|workos.sso\|workos.directorySync\|workos.auditLogs\|workos.fga\|workos.widgets\|workos.events\|workos.webhooks\|workos.pipes\|workos.portal\|workos.organizationDomains\|workos.featureFlags\|workos.types\|workos.mfa\|workos.authorization\|workos.vault\|organizationId\|organization_id\|orgId\|connectionId\|connection_id\|directoryId\|directory_id\|roleSlug\|permission" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find protected route / session access declarations
grep -rn "authkitMiddleware\|withAuth\|getUser\|ensureSignedIn\|getSignInUrl\|getSession\|isAuthenticated\|require_session\|@login_required\|authMiddleware" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find B2B / enterprise feature usage (SSO, SCIM, audit, admin portal, security)
grep -rn "scim\|saml\|sso\|auditLog\|audit_log\|adminPortal\|portalLink\|radar\|pipes" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Check package.json / go.mod / requirements.txt for WorkOS dependencies
find . -maxdepth 3 \( -name "package.json" -o -name "go.mod" -o -name "requirements.txt" \) \
  ! -path "*/node_modules/*" -exec grep -l "workos" {} \;

For each hit, record:

• File path and line — where the change happens
• What it does — import, route protection, claim access, org/tenant read, SSO/SCIM config, webhook handler, logout handler, etc.
• Complexity — Low (drop-in replacement), Medium (logic rewrite), High (no equivalent)

Read package.json (or equivalent) for the exact framework version — this affects async behavior (Next.js 15 vs 14) and SDK compatibility.

If the Descope Docs MCP is available, use docs_search or docs_ask_question to verify current SDK method names for anything you plan to reference in the plan.

---

Step 2: Write MIGRATION-PLAN.md

Write MIGRATION-PLAN.md to the working directory using the triage answers and codebase analysis.

Two audiences: the engineer needs enough technical detail to execute; the PM or tech lead needs scope, risk, and timeline without decoding jargon. Use plain English. Explain technical terms on first use. Open each section with a sentence summarizing what it means before presenting tables or evidence. Say what breaks if a risk is missed, not just that it exists. Pair complexity labels with time estimates; skew toward the lower bound — SDK swaps and mechanical rewrites are usually faster than they look, and repetitive files in a group after the first go much faster. Group execution into phases so parallel vs. sequential work is clear.

The plan must include these sections, in this order:

…

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.