Migration Guide

Already have Apple Sign In working? This guide explains how to migrate to Mushu Auth without disrupting your users.

The Good News

User IDs are preserved. Mushu uses the same Apple sub claim as your existing implementation. No user ID migration needed.

When Apple issues an ID token, it includes a sub (subject) claim that uniquely identifies the user. This is the same whether you validate the token yourself or use Mushu. Your existing user IDs will work unchanged.

Migration Strategy: Parallel Operation

The safest migration path is running both systems in parallel:

Deploy Mushu Auth - Set up and test with new sign-ins
Verify User IDs Match - Compare sub claims between systems
Gradual Rollout - Route new logins to Mushu, existing sessions continue
Full Cutover - Once validated, retire old auth code

Step 1: Set Up Mushu Auth

Configure Mushu with your existing Apple credentials (Team ID, Key ID, private key). The same credentials work for both systems.

mushu auth configure \
  --team-id YOUR_TEAM_ID \
  --key-id YOUR_KEY_ID \
  --key-file AuthKey.p8 \
  --bundle-id com.yourapp.ios

Step 2: Validate User IDs Match

Before migrating users, verify that Mushu returns the same user IDs:

# Sign in via Mushu
curl -X POST https://auth.mushucorp.com/auth/apple \
  -H "Content-Type: application/json" \
  -d '{"id_token": "...", "access_code": "...", "nonce": "..."}'

# Compare user_id with your database

The user_id in Mushu's response should match the sub claim you're already storing.

Step 3: Gradual Rollout

Options for gradual migration:

Approach	How It Works	Risk
Feature flag	Route % of new logins to Mushu	Low
New users only	Existing users stay on old auth	Very low
Full cutover	Switch all at once	Medium

Step 4: Session Migration

No forced logout required. Existing sessions can expire naturally. New logins use Mushu tokens. Users won't notice the transition.

Your existing JWT tokens continue working until they expire. When users naturally need to re-authenticate (token expires, new device), they'll get Mushu tokens.

Rollback Plan

If issues arise, rollback is simple:

Keep your existing auth code deployed (just unused)
To rollback: point clients back to your auth endpoint
Mushu tokens become invalid, users re-authenticate with old system

What About My Existing User Data?

Mushu Auth stores minimal user data (user_id, email, name). Your existing user profiles, preferences, and app data stay in your database. Mushu doesn't replace your database - it just handles authentication.

Common Concerns

"Will all my users get logged out?"

No. Existing sessions continue working. Users only interact with Mushu when they need to re-authenticate (token expiry, new device, explicit logout).

"What if Mushu is down?"

Mushu runs on AWS Lambda with multi-AZ redundancy. Historical uptime is 99.9%+. For token validation, you can cache Mushu's public keys and validate locally.

"Can I migrate back if needed?"

Yes. User IDs are Apple's sub claims - they don't belong to Mushu. You can switch auth providers without losing user identity.

When Migration Makes Sense

Mushu Auth is a good fit if:

You want to add Google Sign In (coming soon)
You need organization/team features
You want managed session infrastructure
You're starting a new project (greenfield)

Self-hosted auth might be better if:

Your current auth is working fine with minimal maintenance
You have strict data locality requirements
You need custom authentication flows

Need Help?

We can help plan your migration. Contact support for a consultation.