• Getting Started
  • What is Stytch?
  • Why should I use the Stytch SDK?
  • What can I do with the Stytch SDK?
    • Consumer apps
    • B2B apps
    • Async Options
  • How do I start using Stytch?
• Requirements
• Installation
• Usage
  • Consumer apps
  • B2B apps
  • Configuration
  • Authenticating
• Documentation
• FAQ
• License

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:

Consumer apps

• 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

B2B apps

• Magic links
  • Send/authenticate magic links via Email
  • Send/authenticate discovery magic links via Email
• Passwords
  • Authenticate a member
  • Check password strength
  • Reset a password
• Discovery
  • Discover member’s existing organizations
  • Create a new organization
  • Exchange a session for a different organization
• SSO
  • Start/authenticate an SSO authentication flow
• Sessions
  • Authenticate/refresh an existing session
  • Revoke a session (Sign out)
• Members
  • Get or fetch the current member object (sync/cached or async options available)
• Organizations
  • Get or fetch the current members’s organization

Async Options

The SDK provides several different mechanisms for handling the asynchronous code, so you can choose what best suits your needs.

• Async/Await
• Combine
• Callbacks

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.

To see in-depth examples of basic, intermediate, and advanced usage of the Stytch SDK, check out our Stytch Tutorials!

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.

1. Open Xcode
2. File > Add Packages
3. Enter https://github.com/stytchauth/stytch-swift
4. 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 one of the Stytch clients (StytchClient or StytchB2BClient), 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" // Perhaps fetched from your backend

    @State private var session: Session?

    var body: some Scene {
        WindowGroup {
            ContentView(session: session) 
                .task {
                    StytchClient.configure(publicToken: stytchPublicToken)
                }
                // 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

1. How does the SDK compare to the API?
   1. 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.
2. What are the some of the default behaviors of the SDK?
   1. 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 cached in memory by the SDK, though these must first be received by a successful authenticate call. 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.)
3. Are there guides or sample apps available to see this in use?
   1. Yes! There is a UIKit example consumer app available here. Also, there is a SwiftUI macOS/iOS Consumer app and a UIKit iOS B2B app included in this repo.

Questions?

Feel free to reach out any time at support@stytch.com, in our Slack, or in our forum.

License

The Stytch Swift SDK is released under the MIT license. See LICENSE for details.