migrate-to-saaskit

name	migrate-to-saaskit
description	Migrates existing auth to SaaSKit so an agent can audit and import it. Use when the user wants to migrate to SaaSKit or replace Auth0 or Clerk. It does not write a first-time login (that's `implement-saaskit`).

Migrate to SaaSKit

Audit existing auth and import it to SaaSKit. Then stop.

Guardrails

• MUST audit and export before any import.
• MUST store original org and user primary keys in external_id.
• MUST set sendInvitationEmail: false on every imported user.
• MUST NOT copy password hashes unless the Scalekit Solutions team does it.
• MUST keep a rollback feature flag through the first rollout window.
• MUST NOT write first-time login, callback, or logout. Name implement-saaskit instead.

Gotchas

• Default language is Node. Same client as implement-saaskit.
• Read SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET. Never SCALEKIT_ENV_URL. Do not prepend https://.
• Audit steps live in references/AUDIT-CHECKLIST.md. Import samples live in references/IMPORT-SAMPLES.md. Open those files. Do not paste them here.
• Users re-authenticate on hosted login (SSO, social, or passwordless). Do not import hashes.
• Rebuild SSO with implement-sso. IdP secrets are not exportable.
• Cut over behind a feature flag. Do not flip all traffic first.
• Dashboard: Authentication → Redirect URLs. Roles live at Roles & Permissions.

Step 1 — Confirm this is a migration

If the app has no existing auth, name implement-saaskit and stop.

Collect the three env names from app.scalekit.com → Developers → Settings → API Credentials. Do not invent values.

Done when: this skill is the right path, and the three env names exist.

Step 2 — Audit and export

Open references/AUDIT-CHECKLIST.md. Complete that checklist. Then stop reading it.

Export users, organizations, roles, and SSO/IdP configs. Keep original primary keys.

Before import:

1. Save one sample JWT or session cookie from the old system
2. Add a feature flag that still routes to the old auth
3. Write the rollback steps

Minimum user fields: email (required), first_name, last_name, email_verified (defaults false).

Done when: the export exists, the flag can roll back, and the audit file is checked off.

Step 3 — Import organizations

Install @scalekit-sdk/node only when the repo has no Scalekit SDK yet. Open references/IMPORT-SAMPLES.md for Python, Go, Java, or cURL.

import { ScalekitClient } from '@scalekit-sdk/node';

const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);

const { organization } = await scalekit.organization.createOrganization(
  org.display_name,
  { externalId: org.external_id }
);

externalId is the source org primary key. Live Node options are externalId, logoUrl, and slug only.

Done when: each source org exists in Scalekit and organization.externalId matches the export.

Step 4 — Import users

Create users after their org exists. Use the Scalekit org id from Step 3.

const { user } = await scalekit.user.createUserAndMembership(organization.id, {
  email: source.email,
  externalId: source.external_id,
  sendInvitationEmail: false,
  userProfile: { firstName: source.first_name, lastName: source.last_name },
});

Batch in parallel. Respect rate limits. Do not send invite email.

Done when: each source user has a membership, sendInvitationEmail was false, and user.externalId matches the export.

Step 5 — Rebuild SSO and redirects

Print this checklist. Wait for the user.

1. Authentication → Redirect URLs → Allowed callback URLs: the app callback
2. Authentication → Redirect URLs → Post logout URLs: the post-logout origin
3. Roles & Permissions: recreate source roles

Name implement-sso to rebuild each IdP connection. Do not copy IdP secrets from Auth0 or Clerk.

Done when: both redirect URLs are registered, roles exist, and implement-sso is named or SSO is waived.

Step 6 — Point the app at SaaSKit

Name implement-saaskit for login, callback, cookies, and logout.

Name manage-saaskit-sessions for validate, refresh, and revoke.

Do not write those routes here.

Done when: those skills are named, and this skill has not written login.

Step 7 — Cut over behind the flag

1. Test login with a small set of migrated users
2. Turn the flag on for 5–10% of traffic
3. Watch Dashboard → Auth Logs
4. Keep rollback on for 48 hours

Done when: a subset of users signs in through SaaSKit, and the flag still rolls back.

Step 8 — Stop

Name run-dryrun to test the env. Name check-saaskit-prod before go-live.

Done when: orgs and users are imported with external_id, the flag is in place, and this skill has stopped.

Reach for

• references/AUDIT-CHECKLIST.md for the audit
• references/IMPORT-SAMPLES.md for other languages
• implement-saaskit for login, callback, cookies, and logout
• implement-sso to rebuild SSO
• run-dryrun to test the env
• check-saaskit-prod for the go-live record

Live lookups

• Docs index: https://docs.scalekit.com/llms.txt
• Migration: https://docs.scalekit.com/fsa/guides/migration-guide/
• Auth0: https://docs.scalekit.com/cookbooks/migrate-from-auth0-to-scalekit/
• MCP: https://mcp.scalekit.com