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](/docs/concepts/multi-tenancy) 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

| Descope resource | What to capture | Authdog target |
| --- | --- | --- |
| Users | `userId`, login IDs, verified email/phone, status, custom attributes | [Users](/docs/users) |
| Tenants | Tenant ID, name, domains, custom attributes | [Organizations](/docs/concepts/organizations) |
| Roles and permissions | Names, permission sets, tenant scope, assignments | [Roles & permissions](/docs/permissions) |
| Flows/auth methods | Password, OTP, magic link, OAuth, passkey, MFA steps | Authentication or [custom flows](/docs/custom-flows) |
| SSO and SCIM | Connection metadata, domains, group mappings | [Integrations](/docs/integrations) and provisioning |
| JWT/session settings | Custom claims, token lifetime, refresh behavior | [Sessions & tokens](/docs/concepts/sessions-tokens) |

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](/docs/concepts/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](/docs/concepts/provisioning).

Descope flows may contain branching, risk checks, forms, connectors, and custom claims. Map each step to Authdog authentication, [components](/docs/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](/docs/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](/docs/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](/docs/users)
- [Organizations](/docs/concepts/organizations)
- [Permissions](/docs/permissions)
- [Provisioning](/docs/concepts/provisioning)
- [Custom flows](/docs/custom-flows)