Configure Native Passkeys for Mobile Logins

On this page

Mobile apps can use the Hypermedia Authentication API (HAAPI) to run an OpenID Connect login in an API driven manner. Passkey logins then run with purely native screens, without invoking the system browser. The client side work is done by the HAAPI SDK, which calls native passkey APIs provided by the mobile operating system. Further background on passkeys is provided in the What are Passkeys? article.

Supported Platforms

At the time of writing, use of passkey APIs is only supported in the iOS HAAPI SDK. It requires version 8.0 or later of the Curity Identity Server, and version 2.5 or later of the HAAPI iOS SDK. In addition, these APIs are only supported on devices running iOS 15 or higher. Android support will be included in an upcoming release of the Curity Identity Server and HAAPI SDKs.

Configure Associated Domains

During native passkeys authentication, the HAAPI SDK calls iOS Native Passkey APIs. The Apple docs describe how a mobile app must first be assigned the Associated Domains capability for the domain where webcredentials are sent for cryptographic verification. This is the domain of the Curity Identity Server, so the app must add that domain under its entitlements:

Native Entitlements

Next, the Curity Identity Server must host an assets file with the name apple-app-site-association at a well-known URL. This must be an HTTPS URL that is accessible over the internet, and use a server certificate from a trusted authority. Apple servers call this URL to verify the app to domain association.


The file registers one or more mobile apps. Its content is similar to the following, where each entry consists of the Apple team ID followed by a bundle ID, in the form com.mycompany.myapp:

"webcredentials": {
"apps": [

Use the Admin UI of the Curity Identity Server to register all mobile apps that use native passkeys. Navigate to System -> Deployment -> Zones. The apple-app-site-association document is then generated for you:

iOS Configured Apps

It is also possible to deploy this file directly, within the webroot folder of the Curity Identity Server. For Docker based deployments, you can place the file at the following location:


Support for generating the equivalent Android configuration, and exposing an assetlinks.json document, is also available in the Curity Identity Server. Once the HAAPI Android SDK is updated to support native passkeys, the same mechanism will therefore work for the Android platform.

Fallback Behavior

If associated domains are not configured correctly, or if an iOS device older than 15 is used, the app will fall back to a browser based flow for passkey logins.

Apple Document Caching

When your iOS app is launched, the operating system contacts Apple servers. As part of this process the apple-app-site-association document is retrieved from the Curity Identity Server and cached on Apple servers. If you edit the document, such as to add a new mobile app, it may take a number of hours before iOS loads the latest version during the verification process. During development, you can ensure immediate feedback by using developer mode:


Add the Passkeys Authenticator

Once you have a compliant device, and the associated domains are registered, simply create a Passkeys Authenticator and configure the app to use it:

Passkeys Authenticator

Test Native Passkeys

Developers can test native passkeys using a purely local setup, by running the HAAPI iOS Code Example on a simulator. When doing so, enable options to simulate biometrics, e.g. by selecting Features / FaceID / Enrolled from the simulator menu.

To enable a working end-to-end setup, first open the app in Xcode, and update its bundle identifier to a unique value, such as com.mycompany.demoapp under Signing & Capabilities. Then configure associated domains for that bundle identifier.

Ensure that you run the example deployment using the USE_NGROK=true option. The ngrok tool creates an HTTP tunnel that is used to expose the Curity Identity Server over an internet HTTPS URL, as described in the Mobile Setup with ngrok tutorial. This provides the publicly available URL that is a prerequisite for native passkeys authentication on mobile devices.

Passkey Logins Video

Once the technical setup is complete, you can run the example application and authenticate with passkeys. The following video shows the passkey flow on a simulator, for both registration and authentication flows:

Manage Device Compatibility

You may need to support customers with iOS devices on versions below 15, for which native passkeys are not supported. To do so, integrate code similar to that in the Demo/Classes/FlowViewModel.swift class of the HAAPI Model SDK Code Example, for both registration and authentication. Older versions will then present a fallback view that triggers opening of the system browser:

private func prepareWebAuthnRegistration(operationStep: WebAuthnRegistrationClientOperationStep) {
if #available(iOS 15.0, *) {
} else {

If a user with an old device attempts to use passkeys, the HAAPI flow will present the following screen, to prompt the user to switch to the system browser:

Native HAAPI Unsupported


When using the Hypermedia Authentication API in a mobile app, you get built-in support for strong user authentication using passkeys, with a purely native login user experience. This tutorial explained the configuration steps. By implementing an OAuth flow in this manner, you don't need to write any code, and your apps will receive tokens with which to call APIs, for an end-to-end security solution.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial