Passkeys with Mobile SDKs

This guide is meant for developers that are NOT using Descope Flows to design login screens and authentication methods.

If you'd like to use Descope Flows, Quick Start should be your starting point.

Descope supports passkeys which allow for users to authenticate via the FIDO Alliance's WebAuthn standard. This standard allows for users to authenticate using a variety of methods including biometrics, hardware tokens, and more.

Client SDK

Install SDK

// 1. Within XCode, go to File > Add Packages
// 2. Search for the URL of the git repo: https://github.com/descope/descope-swift
// 3. Configure your desired dependency rule
// 4. Click Add Package

Import and initialize SDK

Parameters:

baseUrl: Custom domain that must be configured to manage token response in cookies. This makes sure every request to our service is through your custom domain, preventing accidental domain blockages.

import DescopeKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Descope.setup(projectId: "__ProjectID__")
    return true
}

Setup and Authentication

Users can authenticate by creating a new passkey or using an existing one. To enable passkey authentication, first configure your Passkey/WebAuthn settings in the Descope Console.

Make sure Passkey/WebAuthn authentication is enabled and that the top-level domain is configured correctly.

For Android, follow Google's official Add support for Digital Asset Links setup guide. Complete the required asset links and manifest configuration so your app can be associated with your domain.

For iOS and macOS, refer to Apple's Supporting Passkeys guide. Make sure your app has an associated domain configured with the webcredentials service type, and that the value matches the top-level domain configured in the Descope Console.

Passkeys in Your Own WebView on Android

If your Android app loads a Descope flow in a WebView that you manage yourself, such as one using androidx.webkit with setWebAuthenticationSupport, the app finishes the passkey operation under its own APK key hash origin rather than the origin of the page it loaded.

If passkey registration or sign-in fails in that setup, register the app so Descope accepts its origin: add the SHA-256 fingerprint of the keystore used to sign your app under Android Fingerprints in Passkeys Settings.

Important

An empty Android Fingerprints list places no restriction on Android apps. Once you add one fingerprint, the list covers every Android app in the project, so add a fingerprint for each of your apps and for each signing key they use.

Check Passkey Support

Before presenting passkey options to users, check whether passkeys are supported on the current device:

Passkeys require iOS 15 and above. You can check availability at runtime using:

if #available(iOS 15, *) {
    // Passkeys are supported; show passkey UI
} else {
    // Fall back to another authentication method
}

Authenticate with a Passkey

Note

The passkey operations are all suspending functions that perform network requests before and after displaying the modal authentication view.

It is thus recommended to switch the user interface to a loading state before calling them, otherwise the user might accidentally interact with the app when the authentication view is not being displayed.

do {
    showLoading(true)
    let authResponse = try await Descope.passkey.signUpOrIn(loginId: "andy@example.com", options: [])
    let session = DescopeSession(from: authResponse)
    Descope.sessionManager.manageSession(session)
    showHomeScreen() 
} catch DescopeError.oauthNativeCancelled {
    showLoading(false)
    print("Authentication canceled")
} catch {
    showError(error)
}

Was this helpful?

On this page