Client-Side iOS SDK

Prerequisites

Backend — Your server calls POST /v3/unify and the rest of the Unified Authentication sequence; follow Unified Authentication implementation guide.
Access token — Obtain a bearer token using Prove OAuth (Authentication) for server-side API calls.
Xcode — Build with Xcode 16.0 or later (see the warning under Installation).

Installation

The Prove iOS SDK is written in Swift and uses native iOS APIs. Check the SDK package or release notes for supported iOS version ranges and binary size details.

Xcode RequirementTo integrate with our iOS SDKs, build apps with Xcode 16.0 or later.

Use this section to add ProveAuth to an iOS Xcode project using CocoaPods or Swift Package Manager (SPM). Prove hosts artifacts on JFrog; complete one tab only for a given app target.

Prerequisites

Xcode — Use the Xcode version required for your Prove iOS SDK (see the installation warning on this page if present).
CocoaPods path — Ruby and the cocoapods-art plugin; ability to edit the Podfile and run pod install.
SPM path — Swift toolchain with swift package-registry available in your environment (terminal).

Add the dependency

CocoaPods
Swift Package Manager

Configure the Prove CocoaPods source, declare ProveAuth, then install pods.

# Install the cocoapods-art plugin (Artifactory)
gem install cocoapods-art

# Add the Prove pod repository
pod repo-art add prove.jfrog.io https://prove.jfrog.io/artifactory/api/pods/libs-public-cocoapods

# In your Podfile, add the Prove pod repository as a source
plugin 'cocoapods-art', :sources => [
    'prove.jfrog.io'
]

# In your Podfile, add the SDK pod (pin the version you were onboarded to)
pod 'ProveAuth', '6.10.4'

# Install pods
pod install

Upgrading the SDK (CocoaPods)When you upgrade, set a single ProveAuth version in your Podfile. Don’t add separate versions for ProveBase, ProveDeviceAuth, or ProveMobileAuth. CocoaPods resolves those as dependencies of ProveAuth, which keeps the components aligned and helps avoid version conflicts.

Configure the Swift package registry

swift package-registry set --global "https://prove.jfrog.io/artifactory/api/swift/libs-public-swift"
swift package-registry login "https://prove.jfrog.io/artifactory/api/swift/libs-public-swift"
# Press Enter when prompted for access token

Public registryThis registry is publicly accessible; you do not need a password or access token. Press Enter when prompted for an access token.

Complete this registry setup from the command line first. After that, you can add swift.proveauth from Xcode or from Package.swift.

Add the package

Option A — Xcode

In Xcode, choose File → Add Package Dependencies.
Search for swift.proveauth and add it to your target.
For production builds, pin an exact package version (for example 6.10.4) so CI and local builds stay consistent.

After the CLI registry steps above, enter swift.proveauth in the package search field if it does not appear automatically.Option B — Package.swiftAdd the dependency and product to Package.swift:

Swift

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "YourApp",
    platforms: [.iOS(.v12)],
    dependencies: [
        .package(id: "swift.proveauth", from: "6.10.4"),
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: [
                .product(name: "ProveAuth", package: "swift.proveauth"),
            ]
        )
    ]
)

Resolve packages from the package directory:

swift package resolve

Upgrading the SDK (Swift Package Manager)When you upgrade, change only the swift.proveauth package version. Dependent libraries resolve with that package.

Verify

Open the workspace (.xcworkspace for CocoaPods, or your SPM project) and build the app target (⌘B). The project should compile without missing ProveAuth symbols.
If resolution fails, confirm registry / Pod repo commands completed without errors and that you are on a network that can reach prove.jfrog.io.

Send the type of flow: mobile

Unlike the Web SDK, when using the iOS SDK, use the mobile flow. Pass mobile to the server’s Unify() call (POST /v3/unify). In a mobile flow, the phone performs one-time password (OTP) validation. In the mobile flow, once OTP validation is complete, the AuthFinishStep function executes.

`Authenticate()`

The SDK requires an authToken for Authenticate(). Your server returns this from POST /v3/unify. The token is session-specific (single flow) and expires after 15 minutes. See the unify reference for full response fields.

Retrieve `authToken`

To start the flow, send a request to your back-end server with the possession type. Include a phone number if you are using Prove’s possession check. Your backend should call POST /v3/unify and return authToken to the app.

Swift

// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func initialize(phoneNumber: String, possessionType: String, completion: @escaping (Result<String, Error>) -> Void) {
    guard let url = URL(string: "\(backendUrl)/initialize") else {
        completion(.failure(URLError(.badURL)))
        return
    }
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body
    let body: [String: Any] = [
        "phoneNumber": phoneNumber,
        "possessionType": possessionType
    ]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(.failure(error))
        return
    }
    // Perform the request
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle network or connection errors
        if let error = error {
            completion(.failure(error))
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(.failure(statusError))
            return
        }
        guard let data = data else {
            let noDataError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "No data received"])
            completion(.failure(noDataError))
            return
        }
        do {
            if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
                let authToken = json["authToken"] as? String {
                completion(.success(authToken))
            } else {
                let parsingError = NSError(domain: "", code: 0, userInfo: [NSLocalizedDescriptionKey: "Failed to parse JSON or authToken is missing"])
                completion(.failure(parsingError))
            }
        } catch {
            completion(.failure(error))
        }
    }
    // Start the network call
    task.resume()
}

Setup authenticator

Once you have the authToken, build the authenticator for the mobile flow.

Prove Possession
Customer-Supplied OTP with Force Bind

Swift

// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()

// Objects implementing OtpStartStep/OtpFinishStep protocols
let otpStartStep = MobileOtpStartStep()
let otpFinishStep = MobileOtpFinishStep()

let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
    .withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep)
    .build()

Swift

// Object implementing ProveAuthFinishStep protocols
let finishStep = FinishAuthStep()

let proveAuthSdk: ProveAuth
proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
    .build()

If a mobile data connection is unavailable during testing, use the Builder class. It permits simulated successful session results while connected to a Wi-Fi network. Testing using a Wi-Fi connection is useful in the Sandbox environment.

Swift

proveAuthSdk = ProveAuth.builder(authFinish: finishStep)
  .withMobileAuthTestMode() // Test mode flag
  .build()

Performing the authentication

The Prove Auth object is thread safe and used as a singleton. Most Prove Auth methods are blocking and therefore can’t execute in the main app thread. The app employs an executor service with a minimum of two threads to manage threads due to the ability to process concurrent blocking requests.

Swift

// authToken retrieved from your server via StartAuthRequest
proveAuthSdk.authenticate(authToken) { error in
  DispatchQueue.main.async {
    self.messages.finalResultMessage = "ProveAuth.authenticate returned error: \(error.localizedDescription)"
    print(self.messages.finalResultMessage)
  }
}

Validate the mobile phone

In the AuthFinishStep, specify a function to call once the possession checks complete on the mobile phone. In the following code, notice an endpoint called /verify. That backend route should call UnifyStatus() (POST /v3/unify-status) to validate the phone number.

Swift

// Send a verify request.
// The below example uses native iOS URLSession, but any other
// alternative networking approaches should also work
func unifyVerify(authId: String, completion: @escaping (Error?) -> Void) {
    guard let url = URL(string: "\(backendUrl)/verify") else {
        completion(URLError(.badURL))
        return
    }
    // Create the request
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Accept")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    // Set up the request body (empty JSON object) - authId is not needed so you can ignore.
    let body: [String: Any] = ["authId": authId]
    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: body, options: [])
    } catch {
        completion(error)
        return
    }
    // Perform the request
    let task = URLSession.shared.dataTask(with: request) { _, response, error in
        if let error = error {
            completion(error)
            return
        }
        // Check HTTP response status code
        if let httpResponse = response as? HTTPURLResponse,
            httpResponse.statusCode != 200 {
            let statusError = NSError(domain: "", code: httpResponse.statusCode, userInfo: [NSLocalizedDescriptionKey: "HTTP error with status code: \(httpResponse.statusCode)"])
            completion(statusError)
            return
        }
        completion(nil)
    }
    // Start the network call
    task.resume()
}

Configure OTP

To use the Resend/Retry/Phone Change features, install the iOS SDK version 6.5.1 or later.

To set the One-Time Password (OTP) handler, withOtpFallback(otpStart: otpStartStep, otpFinish: otpFinishStep), requires implementing the OtpStartStep and OtpFinishStep. The OTP session has a two minute timeout from when it’s sent through SMS to when the customer can enter in the OTP.

Default
Prompt for Phone Number
Resend
Retry OTP
Phone Number Change

Follow these instructions if you are implementing OTP and you are passing in the phone number on the /unify endpoint. In this case, you’ve already prompted for a phone number so don’t prompt for it in the client SDK.Since you passed the phone number in the Unify() function, call callback.onSuccess(input: nil) to communicate to the SDK you have the customer’s agreement to deliver the SMS message.

Swift

class OtpStartStepNoPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to handle phone number collection for SMS OTP,
    // or to obtain user confirmation for initiating an SMS message.
    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        // Since no phone number is needed, don't prompt the user.
        callback.onSuccess(input: nil)
    }
}

Call the callback.onError() method to communicate to the SDK any issues while trying to obtain the phone number or the OTP. Report an error if the customer cancels the SMS transaction or presses the back button to leave the screen.

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Follow these instructions if implementing MobileAuth in the US and collecting the phone number only if MobileAuth fails. This implements OTP without allowing SMS re-sends and phone number changes. If you want those capabilities, see the Resend, Retry OTP, and Phone Number Change tabs.

International MobileAuth requires phone number input, whereas US MobileAuth allows silent authentication without phone number input.

In the start step, call the callback.onSuccess(input: otpStartInput) method to return the collected phone number to the SDK.

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Implement the finish step:

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Follow these instructions to allow the customer to request a new OTP via SMS using the same phone number. There is a max of three send attempts including the initial message.Implemented the start step:

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

You can then send a new OTP SMS to the same phone number by implementing the finish step like this:

Swift

class OtpFinishStepMultipleResend: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered in the SMS message.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Return the OTP value to the SDK
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Communicate to the SDK any issues when host app trys to obtain the OTP value
    // or when users cancel the OTP flow
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }

    // Call this method to request a new OTP code for the same mobile number.
    func sendNewOtp() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }
        callback.onOtpResend()
    }
}

Follow these instructions to allow the customer to re-enter the OTP PIN if they type it wrong. There is a max of 3 attempts. To implement this capability, pass allowOTPRetry=true on POST /v3/unify.Implement the start step:

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Implement the finish step - no client side code changes necessary. If the OTP is invalid, call the finish step again to prompt the user for a new input. Once you reach the max attempts, the AuthFinish function runs.

Swift

class OtpFinishStepNoPrompt: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Signal to UI components to display OtpFinishView
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Signal to your UI components that the last provided OTP is invalid
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Provide the collected OTP value to the SDK for validation.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // Notify the SDK of any issues encountered while obtaining the OTP value or if the user cancels the OTP flow.
    func handleOtpFinishError() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        callback.onError()
    }
}

Follow these instructions to allow the customer to re-enter their phone number. There is a max of three entries/send attempts.

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

Swift

class OtpStartStepWithPrompt: OtpStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool, phoneValidationError: ProveAuthError?, callback: OtpStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display OtpStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display OtpStartView if a phone number is needed.
                self.sheetObservable.isOtpStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }

        let otpStartInput = OtpStartInput(phoneNumber: phoneNumber)
        // This is how you pass collected phone number to SDK
        callback.onSuccess(input: otpStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the customer explicitly cancels the SMS OTP transaction
    // or presses the back button to exit out the SMS OTP start step screen.
    func handleOtpStartError() {
        guard let callback = self.callback else {
            print("Error: OtpStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

You can prompt for a new phone number by implementing the finish step like this:

Swift

class OtpFinishStepWithPhoneChange: OtpFinishStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: OtpFinishStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to collect the OTP value delivered via SMS.
    func execute(otpError: ProveAuthError?, callback: OtpFinishStepCallback) {
        self.callback = callback
        // Handle the OTP validation error if present.
        // Update your UI to display the OTP finish view.
        DispatchQueue.main.async {
            if case .otpValidationError = otpError {
                print("found otpError: \(String(describing: otpError?.localizedDescription))")
                // Update your UI to indicate that the provided OTP is invalid.
                self.sheetObservable.isOtpValidationError = true
            } else {
                self.sheetObservable.isOtpValidationError = false
            }
            self.sheetObservable.isOtpFinishActive = true
        }
    }

    // Return the collected OTP value to the SDK.
    func handleOtp(_ otp: String) {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set ")
            return
        }

        let otpFinishInput = OtpFinishInput(otp: otp)
        callback.onSuccess(input: otpFinishInput)
    }

    // When callback.onMobileNumberChange() is evoked, OtpStartStep will be re-initiated
    // so that end-users can enter a different phone number via OtpStartStep.
    func handleMobileNumberChange() {
        guard let callback = self.callback else {
            print("Error: OtpFinishStepCallback is not set")
            return
        }
        callback.onMobileNumberChange()
    }
}

Configure Instant Link

Instant Link for iOS is an add-on feature. To enable, contact your Prove representative.

Use this section to configure the iOS client so an Instant Link SMS opens your app and you pass the returned redirect URL to the SDK to resume the session.

Prerequisites

Instant Link is enabled for your project (contact your Prove representative if needed).
Universal Links (recommended) so the SMS redirect opens your app with the full URL string. See Supporting universal links in your app in the Apple documentation.

When building the authenticator, use withInstantLinkFallback(startStep: InstantLinkStartStep, retryStep: InstantLinkRetryStep?). Implement InstantLinkStartStep in every flow. Add InstantLinkRetryStep only if you support Resend or Phone Number Change (see those tabs). When the client supplies a number, pass it in InstantLinkStartInput (for example the phoneNumber field) to callback.onSuccess(...).

Configure the client

Implement the Instant Link start step

Open the tab that matches how the phone number is collected and sent to Prove.

Default
Prompt for Phone Number
Resend
Phone Number Change

Use this path when the server already has the phone number (for example from your initial Start call) and the client must not prompt again.Call callback.onSuccess(input: nil) so the SDK knows the customer agreed to receive the SMS.

Swift

class InstantLinkStartStepNoPrompt: InstantLinkStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to handle phone number collection for instant link,
    // or to obtain user confirmation for initiating an instant link.
    func execute(
        phoneNumberNeeded: Bool,
        phoneValidationError: ProveAuthError?,
        callback: InstantLinkStartStepCallback
    ) {
        self.callback = callback
        // Since no phone number is needed, don't prompt the user.
        callback.onSuccess(input: nil)
    }
}

Use this path when the iOS app collects the number and you do not need resend or phone-number change.Call callback.onSuccess(input: instantLinkStartInput) with the collected number. Call callback.onError() if collection fails, the customer cancels, or they leave the Instant Link start UI (for example with the back button).

Swift

class InstantLinkStartStepWithPrompt: InstantLinkStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool,
        phoneValidationError: ProveAuthError?,
        callback: InstantLinkStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display InstantLinkStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display InstantLinkStartView if a phone number is needed.
                self.sheetObservable.isInstantLinkStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK.
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }

        let instantLinkStartInput = InstantLinkStartInput(phoneNumber: phoneNumber)
        callback.onSuccess(input: instantLinkStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the user cancels the instant link flow or exits the start step screen.
    func handleInstantLinkStartError() {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

To use the Resend/Phone Number Change features, install the iOS SDK version 6.10.2 or later.

Allow a new SMS to the same number (up to three send attempts including the first).Implement the start step:

Swift

class InstantLinkStartStepWithPrompt: InstantLinkStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool,
        phoneValidationError: ProveAuthError?,
        callback: InstantLinkStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display InstantLinkStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display InstantLinkStartView if a phone number is needed.
                self.sheetObservable.isInstantLinkStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK.
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }

        let instantLinkStartInput = InstantLinkStartInput(phoneNumber: phoneNumber)
        callback.onSuccess(input: instantLinkStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the user cancels the instant link flow or exits the start step screen.
    func handleInstantLinkStartError() {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Then implement InstantLinkRetryStep so the customer can request another SMS, for example:

Swift

class InstantLinkRetryStepMultipleResend: InstantLinkRetryStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkRetryStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to present retry options: resend to the same phone number or cancel.
    func execute(callback: InstantLinkRetryStepCallback) {
        self.callback = callback
        // Update your UI to display the InstantLinkRetryView (e.g. "Did you receive a text message?").
        // User can confirm (close modal / finish) or request resend to the same phone number.
        DispatchQueue.main.async {
            self.sheetObservable.isInstantLinkRetryActive = true
        }
    }

    // Call this method to request a new instant link to the same phone number.
    func handleResend() {
        guard let callback = self.callback else {
            print("Error: InstantLinkRetryStepCallback is not set ")
            return
        }
        callback.onResend()
    }

    // Notify the SDK if the user cancels or if the app fails to handle the retry step.
    func handleInstantLinkRetryError() {
        guard let callback = self.callback else {
            print("Error: InstantLinkRetryStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

To use the Resend/Phone Number Change features, install the iOS SDK version 6.10.2 or later.

Allow the customer to re-enter the phone number (up to three entries/send attempts).

Manual Request RequiredTo enable phone number change capabilities on your credentials, contact your Prove representative.

Implement the start step:

Swift

class InstantLinkStartStepWithPrompt: InstantLinkStartStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkStartStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    func execute(
        phoneNumberNeeded: Bool,
        phoneValidationError: ProveAuthError?,
        callback: InstantLinkStartStepCallback
    ) {
        self.callback = callback
        if !phoneNumberNeeded {
            // If no phone number is needed, then don't prompt the user.
            callback.onSuccess(input: nil)
        } else {
            DispatchQueue.main.async {
                // If a phone number validation error is detected, ensure it is handled to provide feedback to the user.
                if case .phoneNumberValidationError = phoneValidationError {
                    print(
                        "found phoneValidationError: \(String(describing: phoneValidationError?.localizedDescription))"
                    )
                    // Update UI components to display InstantLinkStartView with the phone number validation error.
                    self.sheetObservable.isPhoneValidationError = true
                } else {
                    self.sheetObservable.isPhoneValidationError = false
                }
                // Update UI components to display InstantLinkStartView if a phone number is needed.
                self.sheetObservable.isInstantLinkStartActive = true
            }
        }
    }

    // Return collected phone number to the SDK.
    func handlePhoneNumber(phoneNumber: String) {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }

        let instantLinkStartInput = InstantLinkStartInput(phoneNumber: phoneNumber)
        callback.onSuccess(input: instantLinkStartInput)
    }

    // Communicate any issues encountered while trying to obtain the phone number to the SDK.
    // Error should be reported if the user cancels the instant link flow or exits the start step screen.
    func handleInstantLinkStartError() {
        guard let callback = self.callback else {
            print("Error: InstantLinkStartStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Then implement InstantLinkRetryStep to collect a new number, for example:

Swift

class InstantLinkRetryStepPhoneChange: InstantLinkRetryStep {
    @ObservedObject var sheetObservable: SheetObservable
    var callback: InstantLinkRetryStepCallback?

    init(sheetObservable: SheetObservable) {
        self.sheetObservable = sheetObservable
    }

    // Implement this method to present retry options: resend, change phone number, or cancel.
    func execute(callback: InstantLinkRetryStepCallback) {
        self.callback = callback
        // Update your UI to display the InstantLinkRetryView (e.g. "Did you receive a text message?").
        // User can confirm (close modal / finish), request resend, or request phone number change.
        DispatchQueue.main.async {
            self.sheetObservable.isInstantLinkRetryActive = true
        }
    }

    // Call this method to request resend to the same phone number.
    func handleResend() {
        guard let callback = self.callback else {
            print("Error: InstantLinkRetryStepCallback is not set ")
            return
        }
        callback.onResend()
    }

    // When this is invoked, InstantLinkStartStep will be re-initiated so that the user
    // can enter a different phone number.
    func handleMobileNumberChange() {
        guard let callback = self.callback else {
            print("Error: InstantLinkRetryStepCallback is not set ")
            return
        }
        callback.onMobileNumberChange()
    }

    // Notify the SDK if the user cancels or if the app fails to handle the retry step.
    func handleInstantLinkRetryError() {
        guard let callback = self.callback else {
            print("Error: InstantLinkRetryStepCallback is not set ")
            return
        }
        callback.onError()
    }
}

Handle the redirect and resume the session

After you implement the start step above and the user finishes the web step outside your app, Prove redirects to the finalTargetUrl from your server Start call. Your Universal Link handling must deliver that URL into your app so you can pass the full string—including query parameters—into finishInstantLink(redirectUrl:).For how finalTargetUrl fits into server-side Start with Mobile Auth and Instant Link fallback, see Prove Pre-Fill implementation guide.Call finishInstantLink from the entry point that receives the opened URL, for example application(_:open:options:) or application(_:continue:restorationHandler:).

Swift

/// Finishes the Instant Link authentication flow using the redirect URL from the deep link.
/// This is the URL to which the user is redirected after tapping the Instant Link in SMS.
finishInstantLink(redirectUrl: redirectUrl) { error in
  // Handle errors due to invalid format of redirectUrl here
}

The redirect URL is your original finalTargetUrl plus parameters the SDK needs. Example: if Start used https://yourDeepLinkUrl.com, the link might look like https://yourDeepLinkUrl.com?asc=true&authId=some-uuid-string.

Parameter	Meaning
`asc`	`"true"` or `"false"`: whether the server considers the auth session complete.
`authId`	UUID for the session; the SDK uses it to match the redirect to the in-progress client session.

If required parameters are missing or invalid, the SDK surfaces an error via the finishInstantLink completion and does not continue the flow.Verify: In Sandbox, complete a flow where the SMS opens your app with the full URL; finishInstantLink should run and the session should resume without an error from a well-formed redirect.

Get Started

Welcome

Know

Grow

Resources

Client-Side iOS SDK

Prerequisites

Installation

Prerequisites

Add the dependency

Configure the Swift package registry

Add the package

Verify

Send the type of flow: mobile

`Authenticate()`

Retrieve `authToken`

Setup authenticator

Performing the authentication

Validate the mobile phone

Configure OTP

Configure Instant Link

Prerequisites

Configure the client

Get Started

Welcome

Know

Grow

Resources

​Prerequisites

​Installation

​Prerequisites

​Add the dependency

​Configure the Swift package registry

​Add the package

​Verify

​Send the type of flow: mobile

​Authenticate()

​Retrieve authToken

​Setup authenticator

​Performing the authentication

​Validate the mobile phone

​Configure OTP

​Configure Instant Link

​Prerequisites

​Configure the client

Prerequisites

Installation

Prerequisites

Add the dependency

Configure the Swift package registry

Add the package

Verify

Send the type of flow: mobile

`Authenticate()`

Retrieve `authToken`

Setup authenticator

Performing the authentication

Validate the mobile phone

Configure OTP

Configure Instant Link

Prerequisites

Configure the client