Skip to main content
In addition to the reference documentation below, check out our end-to-end guide on how to implement passkeys in mobile apps using Authsignal.

​
Prerequisites

After you have configured your Relying Party you should follow the steps below.
  • iOS
  • Android
To use passkeys you must first setup an associated domain with the webcredentials service type.
1
Host an apple-app-site-association file on the domain that matches your relying party:
GET https://<yourrelyingparty>/.well-known/apple-app-site-association
2
The response JSON should look something like this:
{
   "applinks": {},
   "webcredentials": {
      "apps": ["ABCDE12345.com.example.app"]
   },
   "appclips": {}
}
where ABCDE12345 is your team id and com.example.app is your bundle identifier.
3
In XCode under “Signing & Capabilities” add a webcredentials entry for your domain / relying party e.g. example.com:

​
Creating a passkey

Creating a passkey must be authorized by presenting a challenge with an existing method or tracking an action to obtain a short-lived token. 
let response = await authsignal.passkey.signUp(
    token: "eyJhbGciOiJIUzI....",
    username: "jane.smith@authsignal.com",
    displayName: "Jane Smith"
)
You can also use our SDK to help determine when to display a passkey creation prompt based on whether or not the user has an existing passkey available on their device. 
let showPrompt = await authsignal.passkey.shouldPromptToCreatePasskey()

if showPrompt {
    let response = await authsignal.passkey.signUp(
        token: "eyJhbGciOiJIUzI....",
        username: "jane.smith@authsignal.com",
        ignorePasskeyAlreadyExistsError: true,
    )
}
To learn more about how to conditionally create passkeys refer to our guide on handling passkey availability.

​
Parameters

​
token
string
A short-lived token obtained by tracking an action.
​
username
string
The primary user identifier associated with the passkey, e.g. the user’s email address.
​
displayName
string
An optional secondary user identifier which the OS may display in place of or alongside the username, e.g. the user’s full name.

​
Response

​
response
AuthsignalResponse<SignUpResponse>

​
Using a passkey

Calling signIn will present the passkey sign-in prompt if a credential is available on the device. If the user successfully authenticates with their passkey, send the result token to your server to validate the challenge. 
let response = await authsignal.passkey.signIn(action: "signInWithPasskey")

if let token = response.data?.token {
    // Send token to your backend for validation
}
Because some users may not have a passkey available, you can conditionally present a fallback authentication method by handling error codes returned by the SDK. 
let response = await authsignal.passkey.signIn(action: "signInWithPasskey")

if response.errorCode == "user_canceled" {
  // Present fallback authentication method
}
To learn more about how to handle if passkeys are available when authenticating refer our guide on handling passkey availability.

​
Parameters

​
action
string
A string which determines how the action associated with the passkey sign-in attempt will be named in the Authsignal Portal. Values are validated with the following regex: ^[a-zA-Z0-9_-]{(1, 64)}$.
​
preferImmediatelyAvailableCredentials
boolean
If set to true, the passkey prompt will not be shown when no credentials are available on the device and an error code will be returned. Defaults to true. Set this to false if you want to support signing in with credentials on another device via QR code.

​
Response

​
response
AuthsignalResponse<SignInResponse>

​
Device support

Passkeys are supported from iOS 15 and Android API level 28 or higher. You can detect whether or not the current device supports passkeys by using the isSupported helper method. 
let isSupported = authsignal.passkey.isSupported

​
Passkey autofill (iOS)

This feature requires rendering a text field with the textContentType property. 
userTextField.textContentType = .username
Then when the screen loads, you should initialize the text field for passkey autofill by running the following code. 
let result = await authsignal.passkey.signIn(
    action: "signInWithPasskeyAutofill",
    autofill: true
)

if let token = result.data?.token {
    // The user has focused your text input and authenticated with an existing passkey
    // Send the response token to your server to validate the result of the challenge
}

​
Cancelling a request (iOS)

If you call signIn to present the passkey sign-in prompt, you will need to cancel a request that is already in progress (e.g. an autofill request). 
authsignal.passkey.cancel()
This is typically required if your UI presents an username input with autofill as well as a separate “Sign in with passkey” button.