Skip to main content

iOS Quickstart

Before you start

Example repository

Enable Native API

In the Clerk Dashboard, navigate to the Native applications page and enable the Native API. This is required to integrate Clerk in your native application or browser extension.

Warning

Enabling the Native API opens a public request pathway that bypasses browser-based CAPTCHA challenges. Learn more about how the Native API affects bot protection.

Create a new iOS app

If you don't already have an iOS app, create a new project in Xcode. Select SwiftUI as your interface and Swift as your language. See the Xcode documentation for more information.

Install the Clerk iOS SDK

Follow the Swift Package Manager instructions to install Clerk as a dependency. When prompted for the package URL, enter https://github.com/clerk/clerk-ios. Add ClerkKit to your target. If you choose native components later in this guide, also add ClerkKitUI.

Add your Native Application

Add your iOS application to the Native applications page in the Clerk Dashboard. You will need your iOS app's App ID Prefix and Bundle ID.

Add associated domain capability

To enable seamless authentication flows, you need to add an associated domain capability to your iOS app. This allows your app to work with Clerk's authentication services.

  1. In Xcode, select your project in the Project Navigator.
  2. Select your app target.
  3. Navigate to the Signing & Capabilities tab.
  4. Select the + Capability option.
  5. Search for and add Associated Domains. It will be added as a dropdown to the Signing & Capabilities tab.
  6. Under Associated Domains, add a new entry with the value: webcredentials:{YOUR_FRONTEND_API_URL}

Note

Replace {YOUR_FRONTEND_API_URL} with your .

Configure Clerk

Configure Clerk once at app launch and provide it to your SwiftUI environment.

  1. Inside your new project in Xcode, open your @main app file.
  2. Import ClerkKit.
  3. Configure Clerk with your Clerk in your app's initializer.
  4. Inject Clerk.shared into the SwiftUI environment using .environment(Clerk.shared) so your views can access it.
ClerkQuickstartApp.swift
import SwiftUI
import ClerkKit

@main
struct ClerkQuickstartApp: App {
  init() {
    Clerk.configure(publishableKey: "YOUR_PUBLISHABLE_KEY")
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(Clerk.shared)
    }
  }
}

Conditionally render content

To render content based on whether a user is authenticated or not:

  1. Open your ContentView file.
  2. Import ClerkKit and access the shared Clerk instance that you injected into the environment in the previous step.
  3. Replace the content of the view body with a conditional that checks for a clerk.user.
ContentView.swift
import SwiftUI
import ClerkKit

struct ContentView: View {
  @Environment(Clerk.self) private var clerk

  var body: some View {
    VStack {
      if let user = clerk.user {
        Text("Hello, \(user.id)")
      } else {
        Text("You are signed out")
      }
    }
  }
}

Choose an authentication approach

Choose hosted authentication for the fastest setup, native components for a prebuilt SwiftUI experience, or a custom flow for complete control over the UI.

Hosted authentication opens Account Portal in a browser authentication session. Account Portal supports the sign-in and sign-up methods enabled for your Clerk application.

The following example displays the signed-in user or opens hosted authentication. After authentication, the SDK updates clerk.user with the signed-in user.

ContentView.swift
import SwiftUI
import ClerkKit

struct ContentView: View {
  @Environment(Clerk.self) private var clerk

  var body: some View {
    VStack {
      if let user = clerk.user {
        Text("Hello, \(user.id)")
      } else {
        Button("Sign up") {
          Task {
            do {
              try await clerk.auth.startHostedAuth(mode: .signUp)
            } catch {
              // Handle the error in your app.
            }
          }
        }
      }
    }
  }
}

Clerk provides prebuilt SwiftUI views that handle authentication flows and user management without custom forms.

  • AuthView handles sign-in and sign-up flows, including email verification, password reset, and multi-factor authentication.
  • UserButton displays the user's profile image and opens UserProfileView, where users can manage their account and sign out.

The following example presents AuthView when a signed-out user selects Sign up. Import both ClerkKit and ClerkKitUI when you use prebuilt views:

ContentView.swift
import SwiftUI
import ClerkKit
import ClerkKitUI

struct ContentView: View {
  @State private var authIsPresented = false

  var body: some View {
    VStack {
      UserButton(signedOutContent: {
        Button("Sign up") {
          authIsPresented = true
        }
      })
    }
    .prefetchClerkImages()
    .sheet(isPresented: $authIsPresented) {
      AuthView()
    }
  }
}

Custom flows use ClerkKit authentication methods with your own SwiftUI views. Choose this approach when you need complete control over each screen and authentication step.

The following example creates a basic email and password sign-up form. Clerk emails the user a verification code, so the form shows a code field once the sign-up starts:

ContentView.swift
import SwiftUI
import ClerkKit

struct ContentView: View {
  @Environment(Clerk.self) private var clerk
  @State private var emailAddress = ""
  @State private var password = ""
  @State private var code = ""
  @State private var isVerifying = false

  var body: some View {
    Form {
      if isVerifying {
        TextField("Verification code", text: $code)
          .textContentType(.oneTimeCode)

        Button("Verify") {
          Task {
            do {
              try await clerk.auth.currentSignUp?.verifyEmailCode(code)
            } catch {
              // Handle the error in your app.
            }
          }
        }
      } else {
        TextField("Email address", text: $emailAddress)
          .textContentType(.emailAddress)
          .textInputAutocapitalization(.never)

        SecureField("Password", text: $password)

        Button("Sign up") {
          Task {
            do {
              let signUp = try await clerk.auth.signUp(
                emailAddress: emailAddress,
                password: password
              )
              try await signUp.sendEmailCode()
              isVerifying = true
            } catch {
              // Handle the error in your app.
            }
          }
        }
      }
    }
  }
}

When verifyEmailCode() completes the sign-up, Clerk creates the user, activates the session, and updates clerk.user.

See the iOS authentication reference for the other strategies available through clerk.auth.

Run your project

In Xcode, select Run ▶︎ to build and launch the app.

Create your first user

Once the app launches successfully, select Sign up and complete the authentication flow to create your first user.

Next steps

Explore the most relevant next steps for your SDK using the following guides.

Prebuilt views

Learn how to quickly add authentication to your app using Clerk's suite of views.

Customization with ClerkTheme

Learn how to customize Clerk views using ClerkTheme.

Add native Sign in with Apple

Learn how to add native Sign in with Apple to your Clerk apps on Apple platforms.

Clerk iOS SDK reference

Learn about the Clerk iOS SDK and how to integrate it into your app.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub