Configure the SDK

Basic configuration
Configuration options
Next steps

Available in other SDKs

Call Clerk.configure(publishableKey:options:) once at app launch before accessing Clerk.shared or @Environment(Clerk.self).

Basic configuration

import ClerkKit
import SwiftUI

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

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

Configuration options

Use Clerk.Options to customize logging, telemetry, redirects, and more.

let options = Clerk.Options(
  logLevel: .debug,
  telemetryEnabled: true,
  keychainConfig: .init(
    service: "com.example.shared-auth",
    accessGroup: "ABCDE12345.com.example.shared-auth"
  ),
  proxyUrl: "https://proxy.example.com/__clerk",
  redirectConfig: .init(
    redirectUrl: "myapp://callback",
    callbackUrlScheme: "myapp"
  ),
  watchConnectivityEnabled: true,
  loggerHandler: { logEntry in
    print("[Clerk] \(logEntry.message)")
  },
  middleware: .init(
    request: [
      CustomHeaderMiddleware()
    ],
    response: [
      ResponseDiagnosticsMiddleware()
    ]
  )
)

Clerk.configure(publishableKey: "YOUR_PUBLISHABLE_KEY", options: options)

`Clerk.Options`

Name
keychainConfig
Type
Clerk.Options.KeychainConfig
Description
Controls Keychain storage behavior.
Name
loggerHandler
Type
(@Sendable (LogEntry) -> Void)?
Description
Callback for error-level SDK logs.
Name
logLevel
Type
LogLevel
Description
Minimum SDK log level. Defaults to .error.
Name
middleware
Type
Clerk.Options.MiddlewareConfig
Description
Configuration for request/response middleware.
Name
proxyUrl
Type
URL?
Description
Proxy URL for apps behind a reverse proxy, e.g., https://proxy.example.com/__clerk.
Name
redirectConfig
Type
Clerk.Options.RedirectConfig
Description
OAuth redirect URLs and callback handling.
Name
telemetryEnabled
Type
Bool
Description
Enables development telemetry collection. Defaults to true.
Name
watchConnectivityEnabled
Type
Bool
Description
Keeps an iOS app and its companion watchOS app signed in as the same user. Enable it in both apps. Defaults to false. See Watch Connectivity.

`KeychainConfig`

Name
accessGroup
Type
String?
Description
Keychain access group for sharing the session with other apps. Apps and extensions that use the same service and accessGroup share one session. Defaults to nil, which keeps the session private to the app. See Share sessions across apps.
Name
service
Type
String
Description
Keychain service name. Defaults to the app bundle identifier.

`RedirectConfig`

Name
callbackUrlScheme
Type
String
Description
Callback URL scheme. Defaults to the app bundle identifier.
Name
redirectUrl
Type
String
Description
OAuth redirect URL. Defaults to {bundleIdentifier}://callback.

`MiddlewareConfig`

Name
request
Type
[ClerkRequestMiddleware]
Description
Final-step request middleware for custom headers or diagnostics.
Name
response
Type
[ClerkResponseMiddleware]
Description
Response middleware that runs immediately after a response is received. Custom response middleware runs before Clerk's built-in response middleware.

Next steps

Clerk

Learn how to access Clerk in your app.

iOS Quickstart

Follow the end-to-end setup guide for a Clerk-powered iOS app.

Last updated on Oct 8, 2026

Edit on GitHub

Configure the SDK

Feedback