Migration Guide: stytch-ios → stytch-mobile (iOS)
This guide covers what changed when moving fromStytchCore (the original iOS-only SDK) to StytchConsumerSDK or StytchB2BSDK (the new Kotlin Multiplatform-backed SDK).
What Changed at a Glance
Old SDK (stytch-ios) | New SDK (stytch-mobile) | |
|---|---|---|
| Package | StytchCore / StytchUI from stytchauth/stytch-ios | StytchConsumerSDK / StytchB2BSDK from stytchauth/stytch-ios-sdk |
| Client | StytchClient (global static) | createStytchConsumer(configuration:) (instance-based) |
| Configuration | StytchClient.configure(configuration:) | createStytchConsumer(configuration:) — configure and create in one step |
| Auth state | StytchClient.sessions.onSessionChange (Combine publisher) | stytch.authenticationStateFlow (async sequence) |
| Concurrency | async/await, Combine publishers, and completion handlers (Sourcery-generated) | async/await |
| Deeplinks | StytchClient.handle(url:sessionDurationMinutes:) | stytch.authenticate(url:sessionDurationMinutes:) |
| OAuth result | Two-step: start() returns (token, url), then call authenticate(token:) | One-step: start() returns the full auth response |
| Pre-built UI | StytchUI / StytchUIClient | Not provided — bring your own UI |
| Session migration | — | Automatic — existing sessions are migrated on first launch |
Installation
The Swift Package URL is nowstytchauth/stytch-ios-sdk, and the product names have changed.
Before
After
RemoveStytchCore and StytchUI from your target’s frameworks and add the new product:
Package.swift:
-ObjC linker flag is still required. In your target’s Build Settings, confirm that Other Linker Flags contains -ObjC.
Configuration and Client Initialization
Before: global static + separate configure call
After: factory function returns an instance
createStytchConsumer called again with the same token returns the same object. Storing it as a let constant or passing it through your dependency injection makes the dependency explicit rather than relying on a global.
Authentication State and Session Access
This is the most significant behavioral change. The old SDK spread session and user state across multiple Combine publishers. The new SDK gives you a single async sequence.Before: Combine publishers
After: async sequence
AsyncStream or use the callback-based observer:
API Method Changes
Most method names are consistent, but the namespace and parameter type names have changed. The old SDK namespaced underStytchClient with nested type aliases (e.g., StytchClient.OTP.Parameters); the new SDK uses generated parameter types from the OpenAPI spec.
OTP
otps.send() that accepted the delivery method as an enum. The new SDK splits by channel: otp.sms, otp.email, otp.whatsapp.
Email Magic Links
String rather than URL?.
Passwords
Session Management
sessionDurationMinutes is now a plain Int — the Minutes wrapper is gone.
Deeplinks
Before
After
authenticate() takes a String rather than a URL. Pass url.absoluteString from your onOpenURL or openURLContexts handler.
OAuth
The OAuth flow has been simplified. The old SDK returned an intermediate(token, url) tuple from start() that you then passed to authenticate(). The new SDK completes the entire flow — browser session, redirect handling, and token exchange — inside a single start() call.
Before
After
String rather than URL?. The oauthPresentationContextProvider is the replacement for WebAuthenticationConfiguration.presentationContextProvider.
Concurrency: Combine and Completion Handlers
The old SDK used Sourcery to generate Combine and completion-handler variants of every async method. The new SDK does not generate these — it exposesasync/await only.
If your codebase relies heavily on Combine at call sites, you can bridge with:
onSessionChange), use the authenticationStateObserver callback or bridge authenticationStateFlow with AsyncStream:
B2B SDK
If you usedStytchB2BClient in the old SDK, the migration follows the same pattern. Import StytchB2BSDK and use createStytchB2B(configuration:):
B2BAuthenticationState with .authenticated (carrying member, memberSession, organization), .unauthenticated, and .loading cases.
Pre-Built UI
StytchUI and StytchUIClient are not available in the new SDK. The new SDK is intentionally headless — you have complete control over every pixel of your authentication experience, with no constraints on layout, styling, navigation, or branding. Your existing screens remain yours; you just wire them to the SDK methods directly.
Automatic Session Migration
There’s nothing you need to do. On first launch after upgrading, the new SDK automatically reads and decrypts your users’ existing sessions from the old SDK’sUserDefaults store (StytchEncryptedUserDefaults suite) and migrates them into the new SDK’s storage format. Users who were logged in will remain logged in.