Requirements

Passkeys are supported only on iOS 15 and above. Passkey autofill requires iOS 16 and above.

Installation

Cocoapods

Add Authsignal to your Podfile.

pod 'Authsignal', '~> 1.0.10'

Swift Package Manager

Add the following to the dependencies value of your Package.swift file.

dependencies: [
    .package(
        url: "https://github.com/authsignal/authsignal-ios.git",
        from: "1.0.10"
    )
]

Initialization

Initialize the client with your tenant ID and the API URL for your region.

RegionAPI URL
US (Oregon)https://api.authsignal.com/v1
AU (Sydney)https://au.api.authsignal.com/v1
EU (Dublin)https://eu.api.authsignal.com/v1

You can find your tenant ID in the Authsignal Portal.

Passkeys

Prerequisites

After you have configured your Relying Party you should follow the steps below.

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.

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.

Passkeys represent a new paradigm when compared with traditional authentication methods. To learn more about how to create an optimal sign-in experience for users, refer to our documentation on mobile UX best practices.

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>

Passkey autofill (iOS)

This feature requires rendering a text field with the textContentType property.

Then when the screen loads, you should initialize the text field for passkey autofill by running the following code.

Cancelling an autofill request (iOS)

If you call signIn to present the passkey sign-in prompt, you will need to cancel any autofill request that is already in progress.

This is typically required if your UI presents an username input with autofill as well as a separate “Sign in with passkey” button.

Push

The mobile SDK’s push authentication methods can be used to lookup and respond to authentication requests initiated from another device (e.g. desktop web browser) using public key cryptography.

These authentication requests can either be initiated using the pre-built UI or the client API. For more detail on the integration model for push authentication refer to our sequence diagram.

Adding a credential

Adding a push credential generates a private/public key pair, where the private key is secured on the user’s mobile device and the public key is held by Authsignal.

This operation must be authorized with a short-lived token, which can be obtained by tracking an action from your backend in an authenticated context.

Parameters

token
string

A short-lived token obtained by tracking an action.

Response

response
AuthsignalResponse<boolean>

Removing a credential

Response

response
AuthsignalResponse<boolean>

Getting a challenge

Response

response
AuthsignalResponse<boolean>

Updating a challenge

After presenting the user with a prompt to approve or reject the request, you should update the challenge with their response.

Response

response
AuthsignalResponse<boolean>

Requiring user authentication (Android)

When adding a credential, it is possible to require that the user authenticate whenever they subsequently access the credential (i.e. when approving or rejecting a push challenge).

authsignal.push.addCredential(
    token = token,
    userAuthenticationRequired = true
)

It’s also possible to specify additional user authentication parameters.

authsignal.push.addCredential(
    token = token,
    userAuthenticationRequired = true,
    timeout = 60,
    authorizationType = 0
)

The timeout param determines the time (in seconds) that the credential can be accessed after authenticating - or 0 if authentication must occur for every credential use. The authorizationType param determines if authentication is required via biometrics and/or device credential (e.g. pin).

If user authentication is required for a credential, you must call updateChallenge in a biometric prompt authentication callback.

  1. Initialize a signature before displaying the biometric prompt
val signature = authsignal.push.startSigning()

val cryptoObject = CryptoObject(signature)

// Initialize biometric prompt and prompt info
val biometricPrompt = ...
val promptInfo = ...

biometricPrompt.authenticate(promptInfo, cryptoObject);
  1. Retrieve the signature from the crypto object in your prompt’s authentication callback
override fun onAuthenticationSucceeded(result: AuthenticationResult) {
    super.onAuthenticationSucceeded(result)

    val cryptoObject = result.cryptoObject
    val signer = cryptoObject.signature

    authsignal.push.updateChallenge(
        challengeId = challengeId,
        approved = true,
        signer = signer
    )
}

Email OTP

All email OTP SDK methods require you to set a token first.

Enroll email

Start enrollment for a new email OTP authenticator by sending the user an email containing an OTP code.

This method is typically used when you’ve not yet verified the user’s email address.

If you’ve already verified a user’s email address independently of Authsignal, you can alternatively use a Server SDK to enroll the user programmatically.

Parameters

email
string

The user’s email address.

Response

response
AuthsignalResponse<void>

Challenge email

Start re-authentication for an existing email OTP authenticator by sending the user an email containing an OTP code.

This method is typically used when you’ve already verified the user’s email address.

Response

response
AuthsignalResponse<void>

Verify email

Finish enrolling or re-authenticating a new or existing email OTP authenticator by verifying the code submitted by the user.

Parameters

code
string

The OTP code inputted by the user.

Response

response
AuthsignalResponse<VerifyResponse>
data
VerifyResponse

SMS OTP

All SMS OTP SDK methods require you to set a token first.

Enroll SMS

Start enrollment for a new SMS OTP authenticator by sending the user an SMS containing an OTP code.

This method is typically used when you’ve not yet verified the user’s phone number.

If you’ve already verified a user’s phone number independently of Authsignal, you can alternatively use a Server SDK to enroll the user programmatically.

Parameters

phoneNumber
string

The user’s phone number in E.164 format e.g. +14155552671.

Response

response
AuthsignalResponse<void>

Challenge SMS

Start re-authentication for an existing SMS OTP authenticator by sending the user an SMS containing an OTP code.

This method is typically used when you’ve already verified the user’s phone number.

Response

response
AuthsignalResponse<void>

Verify SMS

Finish enrolling or re-authenticating a new or existing SMS OTP authenticator by verifying the code submitted by the user.

Parameters

code
string

The OTP code inputted by the user.

Response

response
AuthsignalResponse<VerifyResponse>
data
VerifyResponse

Authenticator app (TOTP)

All authenticator app SDK methods require you to set a token first.

Enroll TOTP

Start enrollment for a new TOTP authenticator by generating a QR code to display to the user.

Response

response
AuthsignalResponse<EnrollTotpResponse>
data
EnrollTotpResponse

Verify TOTP

Finish enrolling or re-authenticating a TOTP authenticator by verifying the code submitted by the user.

Parameters

code
string

The OTP code inputted by the user.

Response

response
AuthsignalResponse<VerifyResponse>
data
VerifyResponse

Setting a token

When using mobile SDK methods for email OTP, SMS OTP or authenticator app (TOTP) you must first track an action using a Server SDK or the Server API to generate a time-limited token (valid for 10 minutes by default).

For enrollment flows, you must also specify the scope add:authenticators when tracking the action if the user already has an existing authenticator. For more detail refer to our guide on how to ensure a strong binding when adding authenticators.

Then you can use the SDK’s setToken method. You must use the same token for the initial enroll/challenge call and the subsequent verify call.

Error handling

Mobile SDK methods can return the following fields when encountering an error.

error
string

A description of the error. This value should only be used for logging or troubleshooting purposes.

errorCode
string

A code which identifies a specific error state. This value can be used to drive application logic such as handling when a passkey is not available on the device.

Error codes

network_error

Indicates that an error occurred when making a network request to the Authsignal API. This will occur if the device has no network connection.

expired_token

Indicates that the Authsignal token has expired. This will occur if more than 10 minutes has elapsed since it was generated by tracking an action or since a previous challenge was completed.

token_not_set

Indicates that no Authsignal has been set to authorize the operation. Learn more about setting a token.

user_canceled

Indicates that the user dismissed the passkey sign-in prompt. On iOS this may also indicate that the user has no passkey credential available on the device.

no_credential

Android only. Indicates that the user has no passkey credential available on the device.