Mobile
Learn how to use the Authsignal SDKs for iOS, Android, React Native, and Flutter.
Requirements
Passkeys are supported only on iOS 15 and above. Passkey autofill requires iOS 16 and above.
Installation
Cocoapods
Add Authsignal to your Podfile.
Swift Package Manager
Add the following to the dependencies
value of your Package.swift
file.
Initialization
Initialize the client with your tenant ID and the API URL for your region.
Region | API 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.
Host an apple-app-site-association
file on the domain that matches your relying party:
The response JSON should look something like this:
where ABCDE12345
is your team id and com.example.app
is your bundle identifier.
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
A short-lived token obtained by tracking an action.
The primary user identifier associated with the passkey, e.g. the user’s email address.
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
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
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)}$
.
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
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
A short-lived token obtained by tracking an action.
Response
Removing a credential
Response
Getting a challenge
Response
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
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).
It’s also possible to specify additional user authentication parameters.
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.
- Initialize a signature before displaying the biometric prompt
- Retrieve the signature from the crypto object in your prompt’s authentication callback
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
The user’s email address.
Response
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
Verify email
Finish enrolling or re-authenticating a new or existing email OTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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
The user’s phone number in E.164 format e.g. +14155552671.
Response
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
Verify SMS
Finish enrolling or re-authenticating a new or existing SMS OTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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
Verify TOTP
Finish enrolling or re-authenticating a TOTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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.
A description of the error. This value should only be used for logging or troubleshooting purposes.
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
Indicates that an error occurred when making a network request to the Authsignal API. This will occur if the device has no network connection.
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.
Indicates that no Authsignal has been set to authorize the operation. Learn more about setting a token.
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.
Android only. Indicates that the user has no passkey credential available on the device.