Migration Guide

Documentation Index

Fetch the complete documentation index at: https://docs.prelude.so/llms.txt

Use this file to discover all available pages before exploring further.

​

Prerequisites

• A Prelude account with access to the Auth API.
• An Application ID ($APP_ID) — see Applications.
• Your Management API key ($PRELUDE_API_KEY) for backend calls.

• Base URL: https://api.prelude.dev
• Auth: Authorization: Bearer $PRELUDE_API_KEY
• $USER_ID refers to the Auth user ID (usr_…).

​

Step 1 — Mirror user changes to Auth

​

Where to add the calls

​

Mirroring an update

1. Resolve the Auth user by external_id = your internal user_id. If no Auth user exists yet (the user hasn’t been migrated lazily or by the backfill), skip silently — there’s nothing to mirror.
2. Patch profile fields (first name, last name, picture, locale, …) on the Auth user via the Management API.
3. Reconcile identifiers as a diff, not a replacement:
   • Compute desired = {identifiers on your side} and existing = {Auth identifiers}.
   • Drop everything in existing \ desired.
   • Add everything in desired \ existing.
   • Skip everything in the intersection.
   • Apply the same logic separately for emails, OAuth identifiers (keyed by provider:provider_user_id), phone numbers, etc.
4. Treat NotFound and AlreadyExists errors on individual identifier operations as success — they describe the state you wanted anyway.
5. Don’t short-circuit on the first failure: collect errors across the profile patch and each identifier op, run them all, then join at the end. Partial progress beats an all-or-nothing retry.

​

Mirroring a delete

1. Resolve the Auth user by external_id = your internal user_id.
2. Call the Management API to delete the Auth user.
3. NotFound → treat as success (already gone, which is the desired end state).

​

Management API calls used in this step

​

Step 2 — Migrate active users via the migration hook

​

Configure the migration hook

curl -X POST https://api.prelude.dev/v2/session/apps/$APP_ID/config/migration \
  -H "Authorization: Bearer $PRELUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_validation_url": "https://api.example.com/session/validate"
  }'

​

Frontend flow (auth interceptor)

1. Flag off → use the legacy token, behavior unchanged.
2. Flag on → try session.refresh() first. The SDK returns a cached access token if still valid, otherwise it will hit /refresh.
3. No Auth yet → fetch a token from the legacy provider, call session.migrate({ token: legacyToken }) to exchange it (this method is thread safe with a lock), then session.refresh() to get the fresh Auth access token. Cache that the user is now on Auth for this request.
4. Migration fails → fall back to the legacy token so the user is never locked out.
5. 401 retry → if the request used an Auth token and got Unauthenticated, invalidate the local cache, refresh once, and retry the request a single time. This handles tokens that look valid client-side but were revoked server-side. Keep this rule even after the migration is fully done.

• Don’t loop: retry only once on 401, and only when the failing token was an Auth token.
• Don’t double-migrate: after migrate() succeeds, subsequent calls naturally hit the cached Auth token first, so they skip the legacy path.
• Errors during legacy fetch must be surfaced (e.g. LegacyUnavailableError) so the UI can react — never silently send an unauthenticated request.

​

Backend: accept both tokens

1. Inspect the Authorization: Bearer <token> header.
2. Detect the token type — typically by the iss claim of a JWT, or a token prefix (sess_… vs legacy format), or by trying Auth first and falling back. Pick one detection strategy and stick to it; don’t validate against both signers blindly.
3. Route validation accordingly:
   • Auth token → verify against the Auth JWKS endpoint.
   • Legacy token → verify against the legacy provider as before.
4. Resolve to the same internal user identity in both branches. The user ID, org/tenant, and permissions must come out identical regardless of which token was presented — downstream code shouldn’t care which path it took.
5. Log which path was used with a low-cardinality counter (auth_path{type="session|legacy"}). This is how you know when legacy traffic has drained and the flag can be removed.

​

Source of truth at this stage

​

Step 3 — Backfill dormant users

​

Building the job

1. Iterate your own user table. Your DB is the source of truth for which users you care about. Use keyset pagination ordered by (e.g.) (created_at, id) — LIMIT/OFFSET drifts when rows are inserted mid-scan and can’t resume after a crash. Filter to users that (a) have a legacy provider ID and (b) are not soft-deleted.
2. Batch-fetch the legacy provider. For each DB page, collect the legacy IDs and fetch them from the legacy provider in chunks (most providers cap at ~100 IDs per call).
3. Idempotency check first. For each user, look up Auth by external_id (your internal user_id). If it already resolves to an Auth profile, skip — that user was migrated lazily by the interceptor or by an earlier run of this job.
4. Map legacy account → Auth identifiers. Pull every email and every OAuth external account from the legacy user. Normalize the provider name to whatever Auth expects (some legacy providers prefix it, e.g. oauth_google → google). Map the legacy profile → Auth profile (given name, family name, picture, locale, whatever your app reads). Use the same internal user_id as external_id that the migration hook uses — this is what guarantees the lazy and backfill paths converge on the same Auth user.
5. Write atomically. Send the profile + identifiers to Auth in one call. Treat IdentifierAlreadyExists / ExternalIDAlreadyExists as benign — that’s the race with a concurrent migrate() call. Any other error → log and count as failed, do not halt the job.

​

Create the Auth user

curl -X POST https://api.prelude.dev/v2/session/apps/$APP_ID/users \
  -H "Authorization: Bearer $PRELUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "internal-user-42",
    "profile": {
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "identifiers": [
      { "type": "email_address", "value": "jane@example.com" },
      { "type": "phone_number",  "value": "+15551234567" }
    ]
  }'

​

Step 4 — Use Auth for sign-in and sign-up

​

Before you start

• Backfill must be complete. If a user reaches the new Auth login page and has no Auth profile yet, they cannot sign in.
• Identifier coverage. Audit a sample: do users have at least one identifier per sign-in method you intend to support (email + password, each OAuth provider)? If you’re enabling Google sign-in but only 70% of users have a Google identifier, the other 30% will hit “no account found”.
• Passwords. Most legacy providers won’t let you export password hashes. If yours does and the hash format is compatible with Auth’s verifier, import them with the backfill so existing users keep their passwords. If not, password users will have to use a “forgot password” reset flow on first Auth sign-in — communicate this in advance.

​

Build the new login UI

1. Build new routes powered by the Auth SDK: /login, /signup, /forgot-password, /verify, OAuth callback, etc. Keep them behind a feature flag (isSessionLoginEnabled()) separate from isSessionMigrationEnabled() so you can ramp them independently.
2. Wire each sign-in method Auth-side:
   • Email + password → session.signIn({ email, password }). See Password Authentication.
   • OTP → Auth sends, user clicks/enters code, SDK exchanges for a session. See OTP Login.
   • OAuth → redirect to Auth’s OAuth start URL; Auth handles the provider round-trip and drops the user back on your callback. See Social Login.
3. Preserve the external_id invariant. Whichever method the user picks, the Auth profile they end up authenticated as must be the one whose external_id equals your internal user ID. The backfill already guarantees this — your job is not to break it.

​

Bootstrap an Auth-native sign-up

1. The frontend now holds an Auth access token whose JWT claims identify the user (email, OAuth identifiers, etc.) but external_id is empty.
2. The frontend checks for the absence of external_id in the token and calls a single bootstrap on your backend — e.g. CreateUser — with no body, just the Auth bearer token.
3. The backend verifies the Auth token with one important relaxation: for the CreateUser endpoint only, accept tokens whose external_id claim is missing. Every other endpoint must continue to require it; otherwise an attacker could call any endpoint with a fresh Auth token and skip user creation entirely.
4. The backend provisions the internal user in your own DB and triggers whatever side effects new sign-ups normally do (workspace creation, welcome email, analytics event, etc.). If a user with the same email already exists — e.g. a teammate invited them earlier — link to the existing row instead of creating a duplicate.
5. The backend writes the new internal ID back to Auth via update-external-id. This closes the loop: from this point on, the Auth profile has external_id set, every subsequent token contains it, and the standard auth path applies.
6. Once CreateUser returns, the frontend calls refresh() with cache invalidation to get a fresh token with external_id.

curl -X PUT https://api.prelude.dev/v2/session/apps/$APP_ID/users/$USER_ID/external_id \
  -H "Authorization: Bearer $PRELUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "internal-user-42"
  }'

• Idempotency on the backend. The frontend may retry CreateUser on transient failures. Make CreateUser idempotent: if external_id is already set on the Auth profile, or if a user row already exists for this Auth profile ID / email, return the existing user — don’t insert a second row.
• update-external-id is the source of truth, not your DB write. If the DB insert succeeds but update-external-id fails, the user is half-provisioned. Order the writes so this is recoverable: write the DB row, then update-external-id; on the next bootstrap attempt detect the existing row by Auth profile ID and only retry the update-external-id step.
• Authorization gate on the bootstrap. It accepts tokens without external_id, so make sure it does nothing except provision-or-link the user. No tenant-scoped reads, no admin actions, no side effects that depend on caller identity beyond the Auth profile itself.

​

Source of truth at this stage

​

Step 5 — Re-point backend writes to Auth

• Find every caller of the legacy provider’s SDK. Grep for the legacy client’s import path and inventory each call: who calls it, what does it write, what triggers it? Common categories: admin user CRUD, invitation flows, password resets.
• Replace the call with the equivalent Auth API, not a back-write request. Writing to the legacy provider and waiting for the webhook to push the change to Auth would be slow, indirect, and would re-introduce loops. Write to Auth directly; the back-write pipeline will mirror the change to the legacy provider asynchronously.
• Look users up in Auth by external_id (your internal user ID).

• Mixed-write transactions. If a single endpoint used to write the legacy provider and your DB in the same flow, make sure the new Auth write happens first (or in the right order) so failure modes are unchanged.
• Latency assumptions. Some callers may have implicitly relied on the legacy provider’s response time or webhook delivery; the Auth API may be faster or slower. Re-check anything that loops or polls.
• Permission scopes. Your Auth backend credentials need every write scope the legacy credentials had. Audit before flipping, not after.

​

Subscribe to Auth webhooks

curl -X POST https://api.prelude.dev/v2/session/apps/$APP_ID/webhooks \
  -H "Authorization: Bearer $PRELUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/session/events",
    "verification_token": "a-shared-secret",
    "events": [
      "user.updated",
      "user.profile.updated",
      "user.identifier.created",
      "user.identifier.deleted",
      "user.deleted"
    ]
  }'

curl -X POST https://api.prelude.dev/v2/session/apps/$APP_ID/webhooks/$WEBHOOK_ID/activate \
  -H "Authorization: Bearer $PRELUDE_API_KEY"

​

Final source of truth

​

What’s next?

• Set up Webhooks on the Auth side so your backend reacts to lifecycle events in real time.
• Explore the full Management API for advanced user management.