Getting Started
What is Stytch?
Stytch is an authentication platform, written by developers for developers, with a focus on improving security and user experience via passwordless authentication. Stytch offers direct API integrations, language-specific libraries, and SDKs (like this one) to make the process of setting up an authentication flow for your app as easy as possible.
Why should I use the Stytch SDK?
Stytch's SDKs make it simple to seamlessly onboard, authenticate, and engage users. The Swift SDK provides the easiest way for you to use Stytch on Apple platforms. With just a few lines of code, you can easily authenticate your users and get back to focusing on the core of your product.
import StytchCore
// Initiate login/signup
_ = try await StytchClient.magicLinks.email.loginOrCreate(parameters: .init(email: userEmail))
// Later, handle the subsequent deeplink
_ = try await StytchClient.handle(url: deeplinkUrl)What can I do with the Stytch SDK?
There are a number of authentication products currently supported by the SDK, with additional functionality coming in the near future! The full list of currently supported products is as follows:
- Magic links
- Send/authenticate magic links via Email
- Biometrics
- Authenticate via FaceID/TouchID
- OTPs
- Send/authenticate one-time passcodes via SMS, WhatsApp, Email
- OAuth
- Authenticate with external identity providers such as: Apple, Google, Facebook, GitHub, etc.
- Passwords
- Create or authenticate a user
- Check password strength
- Reset a password
- TOTPs
- Create a new time-based one-time passcode (TOTP) secret for storage in an authenticator app
- Authenticate a TOTP
- Get a user's recovery codes
- Authenticate a recovery code
- Sessions
- Authenticate/refresh an existing session
- Revoke a session (Sign out)
- User Management
- Get or fetch the current user object (sync/cached or async options available)
- Delete factors by id from the current user
Async Options
The SDK provides several different mechanisms for handling the asynchronous code, so you can choose what best suits your needs.
Async/AwaitCombineCallbacks
How do I start using Stytch?
If you are completely new to Stytch, prior to using the SDK you will first need to visit Stytch's homepage, sign up, and create a new project in the dashboard. You'll then need to adjust your SDK configuration — adding your app's bundle id to Authorized environments and enabling any Auth methods you wish to use.
Requirements
The Stytch Swift SDK is compatible with apps targeting the following Apple platforms:
- iOS 13+
- macOS 10.15+
- tvOS 13+
Installation
Swift Package Manager
The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.
- Open Xcode
- File > Add Packages
- Enter https://github.com/stytchauth/stytch-swift
- Choose Package Requirements (Up to next minor, up to next major, etc)
Carthage
Carthage is a decentralized dependency manager for Cocoa. To integrate the Stytch Swift SDK into your Xcode project, add the following to your Cartfile.
binary "https://public-assets-stytch-com.s3.amazonaws.com/sdks/swift/carthage/StytchCore.json"
CocoaPods
CocoaPods is a centralized dependency manager for Swift and Objective-C Cocoa projects. To integrate the Stytch Swift SDK into your Xcode project, add the following to your Podfile.
pod 'Stytch/StytchCore'
Unlike with the other dependency managers, when using CocoaPods you'll import Stytch vs StytchCore.
Usage
Configuration
To start using the StytchClient, you must configure it via one of two techniques: 1) Automatically, by including a StytchConfiguration.plist file in your main app bundle (example) or 2) Programmatically at app launch (see .task {} below.)
Associated Domains
If you are using a redirect authentication product (Email Magic Links/OAuth) you will need to set up Associated Domains on your website and in your app's entitlements (example).
Manual Configuration / Deeplink Handling
This example shows a hypothetical SwiftUI App file, with custom configuration (see .task {}), as well as deeplink/universal link handling.
@main
struct YourApp: App {
private let stytchPublicToken = "your-public-token"
private let hostUrl = URL(string: "https://your-backend.com")!
@State private var session: Session?
var body: some Scene {
WindowGroup {
ContentView(session: session)
.task {
StytchClient.configure(publicToken: stytchPublicToken, hostUrl: hostUrl)
}
// Handle web-browsing/universal deeplinks
.onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { userActivity in
guard let url = userActivity.webpageURL else { return }
handle(url: url)
}
// Handle deeplinks
.onOpenURL(perform: handle(url:))
}
}
private func handle(url: URL) {
Task {
do {
switch try await StytchClient.handle(url: url) {
case let .handled(response):
self.session = response.session
case .notHandled:
// Handle via alternative means
}
} catch { ... }
}
}
}Authenticating
As seen in What can I do with the Stytch SDK?, there are a number of different authentication products available. Here, we'll showcase a simple example of using the OTP product.
One-time Passcodes
This example shows a hypothetical class you could use to manage SMS authentication in your app, delegating much of the work to the StytchClient under the hood.
import StytchCore
final class SMSAuthenticationController {
private let onAuthenticate: (Session, User) -> Void
private var methodId: String?
// phoneNumber must be a valid phone number in E.164 format (e.g. +1XXXXXXXXXX)
func login(phoneNumber: String) async throws {
let response = try await StytchClient.otps.loginOrCreate(
parameters: .init(deliveryMethod: .sms(phoneNumber: phoneNumber))
)
// Store the methodId for the subsequent `authenticate(code:)` call
methodId = response.methodId
}
func authenticate(code: String) async throws {
guard let methodId = methodId else { throw YourCustomError }
let response = try await StytchClient.otps.authenticate(
parameters: .init(code: code, methodId: methodId)
)
onAuthenticate(response.session, response.user)
}
}Documentation
Full reference documentation is available here.
FAQ
- How does the SDK compare to the API?
- The SDK, for the most part, mirrors the API directly — though it provides a more opinionated take on interacting with these methods; managing local state on your behalf and introducing some defaults (viewable in the corresponding init/function reference docs). A primary benefit of using the SDK is that you can interact with Stytch directly from the client, without relaying calls through your backend.
- What are the some of the default behaviors of the SDK?
- A few things here: 1) the session token/JWT will be stored in/retrieved from the system Keychain, so will safely persist across app launches. 2) The session and user objects are not cached by the SDK, these must be pulled from the
authenticateresponses and stored by the application. 3) After a successful authentication call, the SDK will begin polling in the background to refresh the session and its corresponding JWT, to ensure the JWT is always valid (the JWT expires every 5 minutes, regardless of the session expiration.)
- A few things here: 1) the session token/JWT will be stored in/retrieved from the system Keychain, so will safely persist across app launches. 2) The session and user objects are not cached by the SDK, these must be pulled from the
- Are there guides or sample apps available to see this in use?
- Yes! There is a SwiftUI macOS/iOS Demo App included in this repo, available here.
Questions?
Feel free to reach out any time at support@stytch.com or in our Slack
License
The Stytch Swift SDK is released under the MIT license. See LICENSE for details.