Migrate from Descope

Migrate from Descope

Descope tenants map 1:1 to Authio organizations. Custom attributes and OAuth identities are preserved.

What you'll keep, what you'll lose, what you'll gain

  • Keep: Tenants (→ Authio orgs), users, roles within a tenant, custom attributes (preserved under user.metadata.custom), OAuth provider mappings, TOTP enrolled flag, self-provisioning domains (preserved on the Authio org).
  • Lose: Descope sessions, Descope-side flows (you replace these with the Authio hosted UI or SDK).
  • Gain: A first-class CLI, predictable pricing, the same multi-tenant model with a richer management API.

Roles

Descope role names map to Authio's vocabulary:

  • admin, tenant_admin → Authio admin
  • owner, super_admin → Authio owner
  • All others → Authio member

Sessions

Descope sessions are dropped on cutover. Users re-authenticate via passkey or magic-link on next visit.

Step-by-step: CLI

# 1) Fetch tenants + users + sso settings.
H="Authorization: Bearer $DESCOPE_PROJECT_ID:$DESCOPE_MGMT_KEY"
tenants=$(curl -s "https://api.descope.com/v1/mgmt/tenant/all" -H "$H")
users=$(curl -s -X POST "https://api.descope.com/v1/mgmt/user/search" -H "$H" -H 'content-type: application/json' -d '{}')
sso=$(curl -s "https://api.descope.com/v1/mgmt/sso/settings/all" -H "$H")

jq -n --argjson t "$tenants" --argjson u "$users" --argjson s "$sso" \
  '{tenants: $t.tenants, users: $u.users, sso: ($s.sso // [])}' > descope.json

# 2) Dry-run.
authio import descope --input ./descope.json --dry-run | jq '.stats'

# 3) Apply.
authio import descope --input ./descope.json

Step-by-step: dashboard wizard

Visit app.authio.com/migrate/descope.

Live import (paste an API token)

Paste your Descope Project ID + Management Key into the dashboard wizard. Authio pulls tenants, users (with their per-tenant role assignments), and SSO settings live.

  1. Descope console → Settings → Company Settings → Management Keys → generate a new key.
  2. Paste your Project ID and the Management Key into the Authio wizard's Connect with API token tab. The probe hits /v1/mgmt/tenant/all.
  3. Start the job; progress fans out per tenant.
Tokens are encrypted at rest with envelope encryption and the credential row is auto-deleted within 24 hours.

Live import via the CLI

authio import descope \
  --live-token "$DESCOPE_MGMT_KEY" \
  --descope-project-id "$DESCOPE_PROJECT_ID" \
  --dry-run

Post-migration checklist

  • Swap the Descope SDK for the Authio SDK.
  • Re-create SSO connections in Authio's SSO admin portal.
  • If you used Descope Flows for custom auth journeys, the closest Authio equivalents are webhook handlers and the risk engine.
  • Send migration emails.