Migrate from Descope

Move Descope users, tenants, roles, authentication methods, and application sessions to Authdog while preserving stable source IDs. This guide covers export, mapping, credentials, staged cutover, rollback, and validation.

Prerequisites

• An Authdog tenant, project, and environment for staging rehearsal.
• Descope Management API access to export users, tenants, roles, permissions, access keys, and configured authentication flows.
• An inventory of every Descope SDK, flow ID, project ID, token validator, webhook, and SSO/SCIM integration.
• Defined cutover cohorts and rollback criteria.

Migration shape

1. Inventory and export — capture users, tenants, access rules, flows, and connections.
2. Map and import — preserve Descope IDs and recreate Authdog configuration.
3. Parallel run — test controlled cohorts while Descope remains available.
4. Cut over and retire — move remaining traffic, soak, then revoke old access.

1. Inventory Descope

Also inventory service access keys, invitations, trusted devices, risk rules, webhook consumers, redirect URLs, and any app logic that branches on Descope claims.

2. Export users and tenants

Use supported Descope Management API list/export endpoints with pagination. Retain:

• Descope userId as stable source identifier
• Login IDs, primary email/phone, and verification state
• Name, picture, status, and custom attributes
• Tenant IDs and user-to-tenant memberships
• Tenant-scoped and global roles
• OAuth/SSO identity references available through supported APIs
• Created, updated, and last-login timestamps

Store Descope userId as the Authdog external identifier. Keep a separate descope_tenant_id → Authdog organization ID table. Login IDs, emails, and tenant names are mutable and must not replace stable IDs.

Password and authenticator strategy

Do not assume password hashes or authenticator secrets are exportable:

• Compatible hash import — only when Descope provides full hash material and Authdog confirms support for its algorithm, parameters, and encoding.
• Progressive migration — validate a password against Descope once through a server-side bridge, then establish an Authdog credential.
• Passwordless/SSO transition — use magic link, OAuth, or enterprise SSO for users without portable passwords.
• Re-enrollment — require new enrollment for passkeys, TOTP, trusted devices, or recovery codes unless explicit portability is confirmed.

Never log raw credentials or copy MFA seeds into general user metadata.

3. Map tenants, roles, and flows

Model Descope tenants as Authdog organizations when they represent customer workspaces. Create organizations first, then memberships and tenant-scoped roles. Map global Descope roles separately from organization roles, and test users belonging to multiple tenants.

Recreate social, SAML/OIDC, and SCIM connections with Authdog URLs and credentials. Translate group-to-role rules and deprovisioning behavior. See Provisioning.

Descope flows may contain branching, risk checks, forms, connectors, and custom claims. Map each step to Authdog authentication, components, or explicit backend logic; do not treat visual flow definitions as portable configuration.

4. Import and update applications

Import through console tooling or the REST Directory API:

1. Upsert user profile and verified identifiers.
2. Set Descope userId as external identifier.
3. Attach required custom attributes and suspend disabled users.
4. Add organization memberships and mapped roles.
5. Record credential/re-enrollment state.

Replace Descope SDK and flow entry points with Authdog (quickstarts). Configure the environment public key (pk_...), update redirects, and validate Authdog sessions on every backend. Rewrite code that expects Descope tenant, role, permission, or custom JWT claims. Replace webhooks and machine credentials explicitly.

5. Stage cutover and rollback

1. Rehearse users, multi-tenant membership, each auth method, and authorization in staging.
2. Export a baseline and reconcile deltas until production writes move.
3. Move internal users, then one tenant or application cohort.
4. Temporarily accept both issuers only in a measured compatibility layer.
5. Monitor failures, duplicate identity links, MFA re-enrollment, role drift, and SCIM status.
6. After soak, disable Descope flows/callbacks, revoke management and access keys, and remove old validation.

Rollback: route affected cohorts to Descope and restore its flow entry points. Keep Descope IDs and tenant mappings intact; choose one authoritative writer for users and memberships during parallel run.

Validation checklist

• User, tenant, membership, and role counts reconcile.
• Every Descope userId and tenant mapping is retained.
• Password strategy tested without assuming hash portability.
• Passkey/MFA re-enrollment behavior is communicated and verified.
• Multi-tenant users receive correct organization-scoped access.
• OAuth, SSO, SCIM, callbacks, and logout pass end-to-end.
• APIs validate Authdog sessions and required authorization data.
• Delta reconciliation and rollback routing are tested.
• Descope keys and dual-issuer support are removed after soak.

Related

• Users
• Organizations
• Permissions
• Provisioning
• Custom flows