Descope Skills Auth0 To Descope

Auth0 → Descope Migration Skill

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

1. MCP Check — confirm whether the Descope Docs MCP 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.

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

• references/implementation-nuances.md — verified migration patterns for each framework, Auth0 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, or a Widget covers the use case. Engineers integrate once (SDK setup + session validation). All subsequent auth evolution — new methods, MFA changes, UI updates — 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 — use AskUserQuestion rather than proceeding with an assumption. The cost of a wrong assumption compounds across 20+ files. Uncertainty about architecture or intent is always worth a question.

MCP over memory. When the Docs MCP is available (confirmed in Part 1), use ask-question-about-descope 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., Express, Next.js, Flask/FastAPI, Go). The user can always pick "Other."
2. Migration goal — Full cut-over, incremental/phased migration, or just evaluating.
3. Existing user base — Are they migrating an app with active users in Auth0, or starting fresh? This determines whether user migration planning is needed (password hashes, bulk import, phased vs. big-bang cutover, forced re-login on cutover).
4. Preferred migration style — Do they want to embed Descope Flows/Widgets directly (full native migration), or preserve their existing OIDC client library and point it at Descope's OIDC endpoints (OIDC compatibility layer)? Note: B2B features (Organizations/SSO/SCIM management) have no OIDC-layer equivalent and require native SDK calls regardless of path.

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

4. Which Auth0 features are in use? Present the highest-impact categories:

   • Actions / Rules / Hooks (custom login logic)
   • Organizations (multi-tenancy / B2B)
   • FGA / fine-grained authorization
   • Social login / Enterprise SSO

   The user can add others via "Other." Follow up on anything selected — e.g., if Organizations is selected, ask about tenant-scoped SSO, SCIM, and invitations. If FGA is selected, ask about the authorization model.

   Also surface in a follow-up AskUserQuestion if not yet covered:

   • Token Vault / Connected Accounts usage
   • M2M / client credentials apps
   • Custom email templates, Log Streams, Attack Protection, custom domains

After both calls, summarize findings and flag high-complexity items (CIBA, Token Vault, FGA) 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, role management, ReBAC, Outbound Apps.)

Codebase scope

• Are there places in the app that read claims directly from the session token (e.g. token.email, req.auth.permissions)? These need a JWT Template configured before they'll work.
• Do they have Auth0 Actions, Rules, or Hooks? Each one needs to be recreated as a Descope Flow step or JWT Template.
• Are there multiple services or microservices validating Auth0 tokens? 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 migration (if they indicated existing users in Step 0)

• How many users? Under 1,000 → the migration script can pull directly from the Auth0 API. Over 1,000 → Auth0 API pagination breaks; they'll need to export a JSON file via Auth0's User Import/Export extension first.
• Do they use passwords? If yes, they need to open a support ticket with Auth0 to get password hash exports — this takes time, plan for it. Without hashes, users will need to reset passwords or switch to passwordless.
• Big-bang cutover or phased? For zero-disruption, Descope supports session migration (beta) — active Auth0 sessions can be exchanged for Descope tokens without re-auth, but users must already exist in Descope. For phased, the freshlyMigrated custom attribute (set automatically by the migration script) can be used in Flow conditionals to give first-time post-migration users a special onboarding path.
• Are they aware that Auth0 sessions will be invalidated on cutover if not using session migration? Plan for a forced re-login or phased rollout.
• Point them to the descope/descope-migration script (Step 3) and recommend a dry run (--dry-run) before any live run.

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

• If they're using CIBA or @auth0/ai wrappers: flag before going further — these have no Descope equivalent and require custom implementation (see Step 3).
• If they're using Auth0 Token Vault in an AI agent: the migration is Medium complexity; no SDK wrapper exists.
• If they're using Auth0 Log Streams: set up Descope's Audit Webhook Connector before cutover to avoid gaps in event logging.

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

• If the app has a custom SSO settings page: ask whether the SSO Setup Suite + Tenant Profile Widget replaces that code.
• 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 generates emails, initiates SSO, 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 Auth0 import sites
grep -rn "auth0\|@auth0\|express-openid-connect\|nextjs-auth0\|auth0-fastapi\|go-oidc" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=dist --exclude-dir=venv \
  . 2>/dev/null

# Find all Auth0 env var references
grep -rn "AUTH0_\|auth0\." \
  --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 claim / token access patterns (things that may need JWT Template)
grep -rn "token\.\|claims\.\|req\.auth\.\|req\.oidc\.\|session()\." \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find protected route declarations
grep -rn "requiresAuth\|withPageAuthRequired\|withApiAuthRequired\|require_session\|@login_required\|authMiddleware\|isAuthenticated" \
  --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 Auth0 dependencies
find . -maxdepth 3 \( -name "package.json" -o -name "go.mod" -o -name "requirements.txt" \) \
  ! -path "*/node_modules/*" -exec grep -l "auth0" {} \;

For each hit, record:

• File path and line — where the change happens
• What it does — import, route protection, claim access, 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 search-descope-docs or ask-question-about-descope 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:

Overview

2–3 sentences: what's being replaced, what replaces it, and the recommended approach with a one-sentence rationale. Add one sentence on what doesn't change — user-facing login behavior, sessions, and existing accounts are preserved.

Include a Migration at a Glance table:

What's Changing and Why

Prose (not a table) describing what each part of the system does today and what it does after. Example:

Today, Auth0 handles everything related to login: it shows the login UI, issues tokens, and validates them on every API request. After this migration, Descope takes over all of those responsibilities. The login UI becomes a Descope component embedded in the app. Token validation moves to the Descope SDK. The five Auth0 environment variables are replaced by a single Descope Project ID.

Auth0 features in use that need to carry over: [list in plain English, one clause each].

Tailor to triage findings.

Auth Touchpoints: What the Code Analysis Found

Open with the scope count (e.g., "11 files across 4 areas"). Group by area, not file path. Each group gets a sentence on what it does and what changes.

Session handling (3 files) — These files read and validate the current user's login state. They'll be updated to use the Descope session SDK instead of Auth0's.

Login / logout routes (2 files) — These handle the Auth0 redirect-based login flow. Descope replaces this with an embedded UI component; no redirect cycle is needed.

Cover all functional groupings. End with: "Total: N files. Estimated code-change effort: N–N hours."

Feature Migration: Auth0 → Descope

For each Auth0 feature confirmed in triage, write a short paragraph: what it's trying to accomplish, the best Descope approach for that goal, what's different, and what action is required. The best approach may be a Flow, Widget, SSO Setup Suite, or Console configuration rather than a direct SDK equivalent — reason about the intent, not just the API surface. Only recommend SDK code when programmatic control is genuinely required. Example:

Multi-tenancy (Auth0 Organizations → Descope Tenants) Auth0 Organizations group users by company and scope their permissions. Descope has the same concept, called Tenants, and the migration script transfers them automatically. The main difference is how tenant membership appears in the session token — Auth0 uses a flat org_id string, while Descope uses a nested tenants object that includes per-tenant roles. Any backend code that reads req.auth.org_id will need to be updated to read token.tenants. This is a predictable, mechanical change. Effort: Medium (1–2 hours). The migration script handles the data; code changes are localized to token-reading logic.

Only include confirmed features.

Before the Code Can Run: Required Configuration

Some Descope behavior is configured in the console, not in code. List every item that must be set up before the app works, as checkboxes with a plain description of what it is, why it's needed, and roughly how long it takes. Group into "Required before any testing" and "Required before production":

Required before any testing:

• Create a Descope project — Takes 2 minutes. Produces a Project ID that replaces all Auth0 credentials in the app's environment variables.
• Create an authentication flow — Descope uses a visual "flow" to define the login experience (what methods are offered, in what order). The built-in sign-up-or-in flow works for most apps and requires no customization to start.
• Configure a user profile token template — By default, Descope session tokens don't include the user's name, email, or profile photo. This template needs to be configured so the app can display user profile information. Without it, any part of the UI that shows the user's name or email will show nothing after login. (~10 minutes)

Required before production:

• Create roles: admin, member (or whatever the codebase references) — Descope roles must exist in the console before code that assigns them will work.
• Configure social login providers (Google, GitHub, etc.) — OAuth credentials for each provider need to be entered in the console. (~15 minutes per provider)
• (continue for each item found in analysis)

Environment Variables

Diff table with plain-English notes for each removal and addition:

Follow with: "Net change: 5 variables removed, 1–3 added. No secrets need to be rotated on the Auth0 side — those credentials stop being used."

User Migration (only if existing users need to be migrated)

Prose strategy first, then steps. Start with: "X existing users need to be in Descope before cutover." Describe:

• The plan: whether this is big-bang (all users moved before cutover) or phased, and why
• What users will experience: will they need to log in again? Will anything look different?
• The biggest dependency: if password migration requires an Auth0 support ticket, say so plainly and call out that this ticket should be opened immediately — it can take several days

End with a brief checklist of the migration steps at the level a PM can track:

• Open Auth0 support ticket to request password hash export (if applicable) — start immediately
• Export user list from Auth0 (if > 1,000 users)
• Do a dry run of the migration script against the Descope dev project
• Review dry-run output for errors
• Run live migration against staging, then production

Risks and Things to Decide

Things that could affect timeline, user experience, or scope. Write each in plain English with three parts: what it is, what breaks if it's ignored, and what to do. Format each as a named callout:

Risk: User profile data won't appear after login until a token template is configured Descope session tokens don't include name, email, or profile photo by default. Any part of the app that displays user information — profile pages, nav bars, greeting text — will show blank values after migration until the token template is set up in the Descope console. This is a one-time configuration step, not a code change. Action: Configure the token template in the Descope console before running any tests. Estimated time: 10 minutes.

Risk: Password migration requires an Auth0 support request If the app supports password-based login, users' hashed passwords must be exported from Auth0 and imported into Descope. Auth0 only releases these via a support ticket, which can take several days to fulfill. Action: Open the support ticket now, in parallel with development work. Without it, password users will need to reset their passwords after cutover.

Include only applicable risks.

Execution Plan

Open with one sentence: phases run in sequence; steps within a phase can run in parallel. Then labeled phases, each with a time estimate:

Phase 1 — Console Setup (~30–45 minutes, no code required) Can be done by any team member with Descope console access, in parallel with other work.

• Create Descope project, copy Project ID
• Create authentication flow (use the built-in sign-up-or-in to start)
• Configure user profile token template
• Create roles: (list actual roles found)
• Configure social login providers: (list actual providers found)

Phase 2 — Code Changes (~X–Y hours, 1 engineer) Work through files in the order listed. Run a compile check after each group.

• Delete pages/api/auth/[...auth0].ts — no replacement needed (5 min)
• Update environment variables in .env.example and CI config (15 min)
• Rewrite lib/auth.ts session helper (30 min)
• Update _app.tsx — swap UserProvider for Descope AuthProvider (15 min)
• Update 8 protected route files to use new session check (45 min)
• Update lib/logout.ts — two-step logout (15 min)
• Compile check and fix any type errors before proceeding

Phase 3 — User Migration (~1–2 hours, includes dry run) Run against dev/staging first. Do not run against production until Phase 4 passes.

• (steps from user migration section above)

Phase 4 — Testing (~30–45 minutes)

• Compile passes with zero errors
• Server starts, no crashes on startup
• Unauthenticated routes redirect to login correctly
• Login flow completes, user profile data appears (confirms token template is working)
• Logout invalidates session

Phase 5 — Production Cutover

• (cutover-specific steps based on their strategy — maintenance window, phased rollout, etc.)

Total estimated engineering effort: N–N hours across N engineers. Blocking dependencies: (list anything on the critical path — support tickets, console access, etc.)

After writing MIGRATION-PLAN.md, stop and tell the user:

MIGRATION-PLAN.md has been written to your working directory. It maps every auth touchpoint found, lists what needs Console setup before the first test, and calls out risks that could affect the timeline.

Take a look before we start making changes. When you're ready to proceed, say so.

Do not proceed to Part 3 unless the user confirms.

Part 3: Execution

Execute the plan in MIGRATION-PLAN.md Section 8 order. Follow the detailed guidance below for each step.

Context Continuity Protocol

Context can be lost between turns. These rules keep the migration coherent.

Step 3.0 — Create MIGRATION-STATE.md before touching any code.

Write MIGRATION-STATE.md to the working directory from the template below. It's the source of truth for migration state — keep it current throughout execution.

# Migration State

_Last updated: [timestamp of last completed step]_

## Project Context
- Framework: [e.g., Next.js 14, Express + React]
- Language: [TypeScript / Python / Go]
- Package manager: [npm / yarn / pnpm / pip / etc.]
- Migration path: [Path A: OIDC compat / Path B: Full native]
- Migration goal: [Full cutover / Phased / Evaluating]

## Triage Answers
- Existing users: [Yes — N users / No — greenfield]
- Password migration needed: [Yes / No]
- Auth0 features in use: [comma-separated list]
- Multiple environments: [Yes: dev/staging/prod / No]
- Zero-downtime required: [Yes / No]

## Files Inventory
_All files that need to change. Update status after each step._

| File | Change | Status |
|---|---|---|
| `pages/api/auth/[...auth0].ts` | Delete | ⬜ Pending |
| `lib/auth.ts` | Rewrite session helper | ⬜ Pending |
| `middleware.ts` | Update session check | ⬜ Pending |

## Console Setup Checklist
- [ ] Descope project created — Project ID: (fill in when done)
- [ ] JWT template configured
- [ ] Roles created: (list roles)
- [ ] Social providers configured: (list providers)

## Decisions Log
_Non-obvious decisions made during migration — preserves rationale if context is lost._

_(none yet)_

## Current Phase
Phase 1 — Console Setup (not started)

## Next Action
Complete console setup per MIGRATION-PLAN.md before making any code changes.

## Blockers
_(none)_

Rule 1 — Re-read before every turn.

At the start of every execution turn, re-read MIGRATION-PLAN.md and MIGRATION-STATE.md before writing any code or making any decision.

Rule 2 — Verify context before every code change.

If the framework, migration path, triage answers, or next step aren't clear from the conversation, re-read both files before proceeding. Then output a context line:

Migration context: Next.js 14 · Path B · Phase 2, step 3/8 · Next: rewrite lib/auth.ts

If this line can't be filled in accurately, re-read the files first.

Rule 3 — Update MIGRATION-STATE.md immediately after each step.

Mark the file done in the Files Inventory, update "Current Phase" and "Next Action", and append any non-obvious decision to the Decisions Log. Do this before the next step.

Pre-Generation Protocol (apply before writing any code)

Run before generating any import, wrapper type, or helper. Skipping produces code that compiles but fails at runtime.

1. Verify SDK exports before writing any import. When the Docs MCP is available, use ask-question-about-descope to confirm the exact method name, option shape, and return type before writing any SDK call. This is faster and more reliable than reading type declarations. Do not write a method name and add a hedge like "verify the exact name" — just verify it.

When the Docs MCP is unavailable: resolve the package's type declarations (node_modules/<pkg>/dist/types/ or its package.json types field) and confirm the exact exported name and signature. For Go, run go doc. For Python, check the SDK stubs.

Prefer local node_modules/ over GitHub when reading type declarations. Installed packages reflect the exact version in use. If the Descope package isn't installed yet, install it first, then read local type declarations. Only fall back to GitHub if the package can't be installed in the current environment.

This applies to every SDK call you write, not just the first import. Field names on option objects (sendMail vs sendEmail), hook return shapes (useDescope() returns the SDK directly, not { sdk }), and subpath exports (/client vs root) differ just as often.

1a. After rewriting any module, grep for remaining imports of the removed package.

grep -r "from '@/lib/auth0'\|from '@auth0/" --include="*.ts" --include="*.tsx" .

Add remaining hits to the work list.

2. Derive wrapper types from the actual return type. Read the function's declared return type and build the wrapper to match. Auth0's field names, nesting, and flags differ — don't infer from them.

3. Check dependency versions before generating framework-specific code. For Next.js: cookies() and headers() from next/headers are synchronous in v14 and async in v15. Read package.json (or go.mod, requirements.txt) first.

4. When making a helper async, propagate to all callers immediately. In TypeScript, async on a shared utility silently breaks callers that omit await. Grep for all call sites of the changed function and update them in the same pass. The cascade can span 10–20 files.

5. Verify published package versions before writing to package.json or running npm install. Don't reuse Auth0's version number or rely on training data for versions. Before writing any install command:

npm view @descope/node-sdk version
npm view @descope/nextjs-sdk version

If npm is unavailable, leave the version as "latest" and flag it.

Step 1.5: Descope Project Setup & Console Configuration

Several steps require Descope Console setup that can't be done in code. The app compiles without them but won't work at runtime.

Use AskUserQuestion to ask whether they already have a Project ID and working Flow. If yes, skip to verifying items 5–7 — these are easy to miss even for existing projects.

1. Create a project and get your Project ID

• Sign in at console.descope.com
• Your Project ID appears in the top-left project selector and under Project → Settings. It starts with P (e.g. P2abc123...).
• For Next.js client-side code, this becomes NEXT_PUBLIC_DESCOPE_PROJECT_ID. For all server-side SDKs, it's DESCOPE_PROJECT_ID.

2. Get a Management Key (if needed)

Required for: user management API, role/permission management, tenant operations, ReBAC (FGA), Outbound Apps, SCIM configuration. If the app does any server-side user or tenant management, they need this.

• Console → Company → Management Keys → Generate Key
• Store as DESCOPE_MANAGEMENT_KEY. Treat like a secret — never expose client-side.

3. Choose or create a Flow

A Flow is the auth UI sequence. Reference it by Flow ID in the web component.

• Console → Authentication → Flows
• The built-in "sign-up-or-in" flow handles email/password, OTP, and social login. Use it for most migrations.
• To customise: duplicate "sign-up-or-in", rename it, then edit in the visual builder.
• The Flow ID is in the URL when editing and in the flow list.
• There are 100+ Flow templates in the library — check for an existing template before building a custom flow. See references/flows-and-widgets.md → Flows.
• MFA: add an MFA step to the Flow or embed MFA as a subflow. Descope manages MFA enrollment through Flows, not the Management SDK — no equivalent to Auth0 Guardian enrollment tickets. For factor-deletion SDK support by type, see references/implementation-nuances.md → MFA section.

4. Configure authentication methods

• Console → Authentication → select methods (Email OTP, Magic Link, Social, SSO, etc.)
• For social providers (Google, GitHub, etc.): configure OAuth credentials here, then add the provider step to your Flow.
• For enterprise SSO (SAML/OIDC): Console → SSO → configure per tenant. For correct SSO callback and ACS URLs (social OAuth, SAML ACS, what NOT to use), see references/implementation-nuances.md → Social login / SSO section.

5. Configure a JWT Template (almost always needed)

Auth0 includes email, name, and picture in tokens by default. Descope does not.

• Console → Authorization → JWT Templates → New Template
• Add claims: {"email": "{{user.email}}", "name": "{{user.name}}", "picture": "{{user.picture}}"}
• Apply the template to your project. Without this step, any code reading token.email will get undefined after migration.

6. Create roles in the Console (if using RBAC)

Descope roles are referenced by name, not by ID. They must be created manually in the Console before the code that assigns them will work.

• Console → Authorization → RBAC → + Role
• Create each role the app references (e.g. admin, member)

7. Define custom attributes (if using tenant/user metadata)

Auth0 Organization metadata and User app_metadata map to Descope customAttributes. Pre-define them in the Console schema before setting them via the SDK.

• Console → Project → Custom Attributes

8. Env var summary

9. Consider Widgets for management UI

Before migrating custom profile pages, user management pages, or role assignment UI, ask whether a Descope Widget covers the use case. See references/flows-and-widgets.md → Widgets.

After completing console setup: Update MIGRATION-STATE.md — check off each completed item in the Console Setup Checklist, record the Project ID in the file, and set Next Action to the first code change step.

Step 2: Framework-Specific Migration

Read references/implementation-nuances.md in two passes before writing any code:

1. General Insights (always) — covers architecture, feature mapping, and common gotchas that apply to every migration regardless of framework.
2. Framework section (use the file's ToC and offset to jump directly) — read only the section matching the user's stack:
   • Express.js → ## Express.js
   • Flask / Python, FastAPI → ## Flask / Python (FastAPI notes are in the "No drop-in middleware" subsection under General Insights)
   • Next.js (App Router, standalone) → ## Next.js (standalone) + ## Next.js (B2B): Migration Bug Catalog
   • Next.js + separate Express API server → ## Next.js (with separate Express API server)
   • Go → ## Go + Encore
   • LangChain / LangGraph / Vercel AI with FGA or Token Vault → ## Agentic AI Stacks

When a new framework is added to the file, add it to this list.

Express.js

• Remove express-openid-connect; add @descope/node-sdk + cookie-parser
• Replace app.use(auth(config)) with ~20-line custom middleware reading the DS cookie and calling descopeClient.validateSession()
• Add /login route rendering <descope-wc> web component (EJS, plain HTML, etc.)
• Logout: POST to descopeClient.logout(refreshToken) + clear DS/DSR cookies

Key gotchas:

• express-openid-connect handled CSRF and cookie parsing internally. You need cookie-parser explicitly.
• req.oidc.user → req.user (set from validated JWT claims after validateSession())
• requiresAuth() is 3 lines of custom code, not an SDK import.

Flask / Python

• Remove authlib; add descope Python SDK
• Remove /callback route entirely — no code exchange needed
• /login renders the Descope web component instead of calling authorize_redirect()
• Logout: descope_client.logout(refresh_token) + delete cookies
• Drop Flask session; state lives in DS/DSR cookies

Key gotchas:

• authlib stored access_token, id_token, userinfo in Flask server-side session. Descope doesn't use Flask sessions. Drop APP_SECRET_KEY and session imports.
• validate_session() returns a dict of JWT claims. Profile fields aren't there by default — configure a JWT Template first.

Next.js

• @auth0/nextjs-auth0 → @descope/nextjs-sdk + @descope/node-sdk
• UserProvider → AuthProvider (takes projectId prop; must use NEXT_PUBLIC_ prefix)
• useUser() → useSession() + useUser() (Descope separates session state from user data)
• Remove pages/api/auth/[...auth0].tsx catch-all — no server-side OIDC handling
• Add /login page with <Descope> component rendering sign-up-or-in flow; always wire onSuccess — the component does not auto-redirect (see references/implementation-nuances.md → Next.js section)
• withPageAuthRequired → manual useSession() check + redirect
• withApiAuthRequired → call session() at handler top, return 401 manually
• Logout: sdk.logout() via useDescope() hook (not a link to /api/auth/logout)

Client vs. server session access — common source of errors:

• session() from @descope/nextjs-sdk/server — server components, server actions, API routes only
• useSession() + useUser() from @descope/nextjs-sdk/client — React client components
  • useSession() returns { isAuthenticated, sessionToken, ... }
  • useUser() returns the user object from the current session
• Using session() in a client component compiles but throws at runtime (attempts to read cookies in a browser context). Scan for this pattern before finishing any Next.js migration.

Server-side session — exact SDK API (verify before generating):

The @descope/nextjs-sdk/server entry exports exactly:

• session(config?) — reads session from request headers/cookies in a server component or server action. No req argument. Returns Promise<AuthenticationInfo | undefined>.
• getSession(req, config?) — reads from an explicit NextApiRequest. API routes only.
• authMiddleware(options) — Next.js middleware factory.

getServerSession does not exist. The name looks plausible but isn't exported. Before writing any import, open node_modules/@descope/nextjs-sdk/dist/types/server/index.d.ts and confirm the export list.

Session return type — AuthenticationInfo, not an Auth0-style session object:

session() returns AuthenticationInfo | undefined from @descope/node-sdk:

interface AuthenticationInfo {
  jwt: string    // raw session JWT
  token: Token   // decoded claims: { sub?, exp?, iss?, [claim: string]: unknown }
  cookies?: string[]
}

There is no isAuthenticated, no claims field, and no user wrapper. Write an adapter function instead:

import { session as sdkSession } from "@descope/nextjs-sdk/server"

export async function getDescopeSession() {
  const authInfo = await sdkSession()
  if (!authInfo) return null
  return { isAuthenticated: true as const, jwt: authInfo.jwt, token: authInfo.token }
}

Then generate all server components using getDescopeSession() from this local file, not from the SDK directly.

For apps with a separate API server (Express):

• Remove express-jwt + jwks-rsa; replace with descopeClient.validateSession()
• Forward the DS cookie as Authorization: Bearer <DS> from Next.js to the API
• No separate access token — the session token is the bearer token

FastAPI / Python

• Remove auth0-fastapi (AuthConfig, auto-mounted /api/auth/* routes, require_session)
• Add custom TokenVerifier class: reads Authorization header, validates against Descope JWKS, attaches claims as FastAPI Security() dependency
• No auto-mounted routes; no session store

Path A: OIDC Compatibility (lower risk, incremental)

Descope exposes standard OIDC endpoints. If the app uses an OIDC client library (express-openid-connect, go-oidc, authlib, @auth0/nextjs-auth0 v4, etc.), it can point at Descope's OIDC issuer instead of Auth0's with minimal code changes:

…(truncated)