# iOS Quickstart

**Example Repository**

- [iOS Quickstart Repo](https://github.com/clerk/clerk-ios/tree/main/Examples/Quickstart)

**Before you start**

- [Set up a Clerk application](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md?sdk=ios)

1. ## Enable Native API

   In the Clerk Dashboard, navigate to the [**Native applications**](https://dashboard.clerk.com/~/native-applications) page and enable the Native API. This is required to integrate Clerk in your native application or browser extension.

   > 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](https://clerk.com/docs/guides/secure/bot-protection.md?sdk=ios#native-api-and-captcha).
2. ## 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](https://developer.apple.com/documentation/xcode/creating-an-xcode-project-for-an-app) for more information.
3. ## Install the Clerk iOS SDK

   Follow [the Swift Package Manager instructions](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) 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`.
4. ## Add your Native Application

   Add your iOS application to the [**Native applications**](https://dashboard.clerk.com/~/native-applications) page in the Clerk Dashboard. You will need your iOS app's **App ID Prefix** and **Bundle ID**.
5. ## 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}`

   > Replace `{YOUR_FRONTEND_API_URL}` with your Frontend API URL.
6. ## 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 Publishable Key in your app's initializer.
   4. Inject `Clerk.shared` into the SwiftUI environment using `.environment(Clerk.shared)` so your views can access it.

   filename: ClerkQuickstartApp.swift

   ```swift
   import SwiftUI
   import ClerkKit

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

     var body: some Scene {
       WindowGroup {
         ContentView()
           .environment(Clerk.shared)
       }
     }
   }
   ```
7. ## 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`.

   filename: ContentView\.swift

   ```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")
         }
       }
     }
   }
   ```
8. ## 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**

   [Hosted authentication](https://clerk.com/docs/ios/guides/account-portal/hosted-auth.md) 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.

   filename: ContentView\.swift

   ```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.
               }
             }
           }
         }
       }
     }
   }
   ```

   **Native components**

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

   - [AuthView](https://clerk.com/docs/ios/reference/views/authentication/auth-view.md) handles sign-in and sign-up flows, including email verification, password reset, and multi-factor authentication.
   - [UserButton](https://clerk.com/docs/ios/reference/views/user/user-button.md) displays the user's profile image and opens [UserProfileView](https://clerk.com/docs/ios/reference/views/user/user-profile-view.md), 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:

   filename: ContentView\.swift

   ```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 flow**

   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:

   filename: ContentView\.swift

   ```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](https://clerk.com/docs/ios/reference/native-mobile/auth.md) for the other strategies available through `clerk.auth`.
9. ## Run your project

   In Xcode, select `Run ▶︎` to build and launch the app.
10. ## 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](https://clerk.com/docs/ios/reference/views/overview.md): Learn how to quickly add authentication to your app using Clerk's suite of views.
- [Customization with ClerkTheme](https://clerk.com/docs/ios/guides/customizing-clerk/clerk-theme.md): Learn how to customize Clerk views using 
- [Add native Sign in with Apple](https://clerk.com/docs/guides/configure/auth-strategies/sign-in-with-apple.md?sdk=ios): Learn how to add native Sign in with Apple to your Clerk apps on Apple platforms.
- [Clerk iOS SDK reference](https://clerk.com/docs/reference/native-mobile/overview.md?sdk=ios): Learn about the Clerk iOS SDK and how to integrate it into your app.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)