Auth0 Swift Integration

CredentialsManager

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

bash

gh api repos/auth0/Auth0.swift/releases/latest --jq '.tag_name'

Use the returned version in all dependency lines instead of any hardcoded version below. Current known version:

2.18.0

.

When NOT to Use

• Android apps: Use auth0-android
• React Native apps: Use auth0-react-native
• Flutter apps: Use the native Flutter Auth0 SDK
• Web SPAs (React, Angular, Vue): Use auth0-react, auth0-angular, or auth0-vue
• Node.js/Express servers: Use auth0-express

Prerequisites

• iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
• Xcode 16.x
• Swift 6.0+
• Auth0 account — Sign up free
• Node.js 20+ (for bootstrap script automation)
• Auth0 CLI —

  brew install auth0/auth0-cli/auth0

  (for bootstrap script)

Quick Start Workflow

Agent instruction: Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling

AskUserQuestion

to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.

Step 1 — Install SDK

Agent instruction: Check the project directory for an existing package manager file:

• Podfile

  present → CocoaPods

• Cartfile

  present → Carthage

• Package.swift

  present → Swift Package Manager

If none are found, ask via

AskUserQuestion

: "Which dependency manager does your project use — Swift Package Manager, CocoaPods, or Carthage?"

Swift Package Manager —

Package.swift

project: Run this command in the project root to add the dependency automatically, then add

"Auth0"

to the target's

dependencies

array in

Package.swift

:

bash

swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0

Swift Package Manager — Xcode project (

.xcodeproj

, no

Package.swift

): The CLI command does not apply. Instruct the user to add the package via Xcode: File → Add Package Dependencies →

https://github.com/auth0/Auth0.swift

→ Up to Next Major Version from

2.18.0

.

CocoaPods or Carthage: Follow the matching installation steps in Setup Guide. Do not just show the instructions — perform the file edits and run the commands.

Step 2 — Configure Auth0

Agent instruction:

• If Auth0 credentials (domain AND client ID) are already in the user's prompt: Write

  Auth0.plist

  directly with those values and proceed to Step 3.
• If no credentials are provided: Run the bootstrap script — do NOT ask the user to create or configure an Auth0 application manually. Always use the CLI path.

Follow Setup Guide — Auth0 Configuration for pre-flight checks and the script command.

Step 3 — Configure Callback URLs

Agent instruction:

1. Read

   Auth0.plist

   to obtain

   ClientId

   and

   Domain

   .
2. Extract the bundle identifier from

   project.pbxproj

   : search for

   PRODUCT_BUNDLE_IDENTIFIER

   , skip values containing

   $(

   or

   Tests

   .
3. Ask the user via

   AskUserQuestion

   : "Which callback URL scheme would you like to use?"
   • Custom scheme (

     {bundle}://

     ) — simpler, works on all Apple platforms
   • HTTPS Universal Links — recommended for production; prevents URL scheme hijacking

Then follow only the matching path below.

Path A — Custom Scheme

Agent instruction: Register the callback URLs using the Auth0 CLI (substitute real values for

CLIENT_ID

,

BUNDLE_ID

,

DOMAIN

):

bash

auth0 apps update CLIENT_ID \
  --callbacks "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input

Then follow the URL scheme registration steps in Setup Guide to register

$(PRODUCT_BUNDLE_IDENTIFIER)

as a URL type in Xcode.

Path B — HTTPS Universal Links

Agent instruction: All four steps below are required — skipping any one will cause the callback redirect to fail silently after login.

Step B1 — Register callback URLs via Auth0 CLI: Register both HTTPS and custom scheme so the app works in all scenarios:

bash

auth0 apps update CLIENT_ID \
  --callbacks "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --logout-urls "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
  --no-input

Step B2 — Configure Device Settings via Auth0 CLI: Extract

DEVELOPMENT_TEAM

from

project.pbxproj

(10-character value, e.g.

ABC12DE34F

). If not found, ask via

AskUserQuestion

: "What is your Apple Team ID? (developer.apple.com → Account → Membership Details)"

bash

auth0 api patch applications/CLIENT_ID \
  --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
  --no-input

Auth0 will now host

https://DOMAIN/.well-known/apple-app-site-association

automatically — required for Universal Links to work on device.

Step B3 — Add Associated Domains entitlement in Xcode: Add

com.apple.developer.associated-domains

to the app's

.entitlements

file with both

applinks:

and

webcredentials:

entries for the Auth0 domain. See Setup Guide — Associated Domains for the complete entitlements XML, Xcode capability steps, and build settings verification.

Step B4 — Use

.useHTTPS()

in the SDK:

swift

Auth0.webAuth().useHTTPS()

Step 4 — Implement Authentication

Agent instruction: Search the project for

@main struct

(SwiftUI) or

AppDelegate

/

UIViewController

(UIKit) to detect the UI framework. If ambiguous, ask via

AskUserQuestion

: "Does your app use SwiftUI or UIKit?" Then follow only the matching path below.

SwiftUI

Agent instruction: Create

AuthenticationService.swift

as an

ObservableObject

, then wire it into the app entry point and root view. Search for the

@main

struct and

ContentView

(or equivalent root view) and update them as shown.

// AuthenticationService.swift
import Auth0
import Combine

class AuthenticationService: ObservableObject {
    @Published var isAuthenticated = false
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    init() { isAuthenticated = credentialsManager.canRenew() }

    func login() async {
        do {
            let credentials = try await Auth0
                .webAuth()
                .useHTTPS()
                .scope("openid profile email offline_access")
                .start()
            _ = credentialsManager.store(credentials: credentials)
            await MainActor.run { isAuthenticated = true }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }

    func logout() async {
        do { try await Auth0.webAuth().useHTTPS().clearSession() }
        catch { print("Logout failed: \(error)") }
        _ = credentialsManager.clear()
        await MainActor.run { isAuthenticated = false }
    }
}

// @main App struct — inject AuthenticationService as environment object
@StateObject private var auth = AuthenticationService()
// In body: ContentView().environmentObject(auth)

// Root ContentView — branch on authentication state
@EnvironmentObject var auth: AuthenticationService
// In body: if auth.isAuthenticated { HomeView() } else { LoginView() }

UIKit

Agent instruction: Create

AuthenticationService.swift

as a plain class, then add login/logout calls to the relevant

UIViewController

. Also check whether the app uses

SFSafariViewController

— if so, add

WebAuthentication.resume(with:)

to

AppDelegate

/

SceneDelegate

(see note below).

// AuthenticationService.swift
import Auth0

class AuthenticationService {
    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())

    var isAuthenticated: Bool { credentialsManager.canRenew() }

    func login() async throws {
        let credentials = try await Auth0
            .webAuth()
            .useHTTPS()
            .scope("openid profile email offline_access")
            .start()
        _ = credentialsManager.store(credentials: credentials)
    }

    func logout() async throws {
        try await Auth0.webAuth().useHTTPS().clearSession()
        _ = credentialsManager.clear()
    }
}

// In your UIViewController
private let auth = AuthenticationService()

@IBAction func loginTapped(_ sender: UIButton) {
    Task {
        do {
            try await auth.login()
            await MainActor.run { navigateToHome() }
        } catch WebAuthError.userCancelled { }
        catch { print("Login failed: \(error)") }
    }
}

@IBAction func logoutTapped(_ sender: UIButton) {
    Task {
        do { try await auth.logout() }
        catch { print("Logout failed: \(error)") }
        await MainActor.run { navigateToLogin() }
    }
}

Note — SFSafariViewController only: If the app uses

.provider(WebAuthentication.safariProvider())

instead of the default

ASWebAuthenticationSession

, add

WebAuthentication.resume(with: url)

to

AppDelegate.application(_:open:url:options:)

and

SceneDelegate.scene(_:openURLContexts:)

. See Integration Patterns for the exact code.

Step 5 — Verify Build

Agent instruction: Run a build to verify the integration compiles without errors:

bash

xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"

If the build fails, review error messages and fix up to 5 times before asking the user.

Detailed Documentation

• Setup Guide — Auth0 Dashboard configuration, bootstrap script, manual setup, URL scheme registration, CocoaPods/SPM/Carthage install
• Integration Patterns — Web Auth login/logout, CredentialsManager, biometric protection, MFA, organizations, error handling, SwiftUI/UIKit patterns
• API Reference & Testing — Full API reference, configuration options, claims reference, testing checklist, troubleshooting

Common Mistakes

https://

{bundle}://

Auth0.plist

offline_access

"offline_access"

UserDefaults

CredentialsManager

credentialsManager.credentials()

store()

.xcodeproj

.xcworkspace

.xcworkspace

pod install

clearSession()

clearSession()

.xcworkspace

Related Skills

• auth0-quickstart

  - Basic Auth0 setup

• auth0-cli

  - Manage Auth0 resources from the terminal

References

• Auth0.swift GitHub
• iOS/macOS Quickstart
• Auth0.swift API Documentation
• Auth0 Dashboard
• EXAMPLES.md