Mobile - Authsignal

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"
    )
]

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"
    )
]

Ensure that you have mavenCentral listed in your project’s buildscript repositories section.

buildscript {
    repositories {
        mavenCentral()
        ...
    }
}

Add the following to your app’s build.gradle file.

implementation 'com.authsignal:authsignal-android:2.0.2'

Install using yarn.

yarn add react-native-authsignal

Then link the native iOS dependencies.

npx pod-install ios

Add the package dependency to your app.

flutter pub add authsignal_flutter

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.

import Authsignal

let authsignal = Authsignal(
    tenantID: "YOUR_TENANT_ID",
    baseURL: "YOUR_REGION_BASE_URL"
)

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:

GET https://<yourrelyingparty>/.well-known/apple-app-site-association

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.

In XCode under “Signing & Capabilities” add a webcredentials entry for your domain / relying party e.g. example.com:

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:

GET https://<yourrelyingparty>/.well-known/apple-app-site-association

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.

In XCode under “Signing & Capabilities” add a webcredentials entry for your domain / relying party e.g. example.com:

To use passkeys on Android you must setup a Digital Asset Links JSON file on your web domain.

Host an assetlinks.json file on the domain that matches your relying party:

GET https://<yourrelyingparty>/.well-known/assetlinks.json

The response JSON should look something like this:

[{
    "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
    ],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example",
        "sha256_cert_fingerprints": [
            "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
        ]
    }
}]

but with the package name and SHA256 fingerprint updated to match your own app.

For more information on this step refer to Google’s documentation on Credential Manager.

Finally, you will need to add an expected origin value for your APK hash when configuring passkeys in the Authsignal Portal.

Setting an expected origin value for your APK hash

One way to obtain your app’s APK hash is to run a signing report.

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: "eyJhbGciOiJ...",
    username: "jane@authsignal.com",
    displayName: "Jane Smith"
)

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>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

errorCode

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: token_not_set, expired_token, network_error or user_canceled.

data

SignUpResponse

Show properties

token

string

A new token which can optionally be used to bind another authenticator for the user.

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 server to validate the result
}

Check out our best practice guide for passkeys on mobile for tips on how to implement an optimal passkey UX by handling error codes returned when no credential is available on the device.

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>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

errorCode

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: user_canceled or no_credential (Android only). These values can be used to handle if a passkey is not available on the device.

data

SignInResponse

Show properties

isVerified

boolean

True if the passkey sign-in attempt was successful.

token

string

A new token which can be used to validate the challenge on your server or optionally to bind another authenticator for the user.

userId

string

The ID of the Authsignal user if the sign-in attempt was successful.

userAuthenticatorId

string

The ID of the Authsignal user authenticator if the sign-in attempt was successful.

username

string

The username associated with the passkey if the sign-in attempt was successful.

displayName

string

The display name associated with the passkey if the sign-in attempt was successful.

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.

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.

await authsignal.push.addCredential(token: "eyJhbGciOiJ...")

Parameters

token

string

A short-lived token obtained by tracking an action.

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

errorCode

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: token_not_set, expired_token or network_error.

data

boolean

True if the push credential was successfully added.

Removing a credential

await authsignal.push.removeCredential()

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error. This could occur if the credential on the device is no longer valid because the corresponding user authenticator has been deleted in the Authsignal Portal.

data

boolean

True if the push credential was successfully removed.

Getting a challenge

let response = await authsignal.push.getChallenge()

if let error = result.error {
    // The credential stored on the device is invalid
} else if let challenge = result.data {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    let challengeId = challenge.challengeId
} else {
    // No pending challenge request
}

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

data

PushChallenge

Show properties

challengeId

string

required

The ID of the challenge corresponding to a particular push authentication request.

actionCode

string

The action code identifying the action associated with the challenge.

idempotencyKey

string

The idempotency key identifying the action associated with the challenge.

userAgent

string

The user agent of the device which initiated the challenge. Present if passed as input to the original track request.

deviceId

string

The device ID of the device which initiated the challenge. Present if passed as input to the original track request.

ipAddress

string

The IP address of the device which initiated the challenge. Present if passed as input to the original track request.

Updating a challenge

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

await authsignal.push.updateChallenge(
    challengeId: challengeId,
    approved: true
)

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

data

boolean

True if the push credential was successfully updated.

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.

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);

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
    )
}

Device

The mobile SDK’s device authentication methods can be used to respond to authentication requests using public key cryptography. For more details of the different use cases, see the Device authentication method documentation.

Adding a credential

Adding a device 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.

await authsignal.device.addCredential(token: "eyJhbGciOiJ...")

Parameters

token

string

A short-lived token obtained by tracking an action.

Response

response

AuthsignalResponse<DeviceCredential>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

errorCode

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: token_not_set, expired_token or network_error.

data

DeviceCredential

Show properties

credentialId

string

required

The ID of the device credential.

createdAt

string

required

The date and time the device credential was created.

userId

string

required

The user ID of the user that the device credential belongs to.

Removing a credential

await authsignal.device.removeCredential()

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

data

boolean

True if the device credential was successfully removed.

Getting a challenge

let response = await authsignal.device.getChallenge()

if let error = result.error {
    // The credential stored on the device is invalid
} else if let challenge = result.data {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    let challengeId = challenge.challengeId
} else {
    // No pending challenge request
}

Response

response

AuthsignalResponse<DeviceChallenge>

Show properties

error

string

data

DeviceChallenge

Show properties

challengeId

string

required

The ID of the challenge corresponding to a particular device authentication request.

actionCode

string

The action code identifying the action associated with the challenge.

idempotencyKey

string

The idempotency key identifying the action associated with the challenge.

userAgent

string

The user agent of the device which initiated the challenge. Present if passed as input to the original track request.

deviceId

string

The device ID of the device which initiated the challenge. Present if passed as input to the original track request.

ipAddress

string

The IP address of the device which initiated the challenge. Present if passed as input to the original track request.

Claiming a challenge

When the user scans the QR code, you should call claimChallenge to set the user attempting to complete the challenge. This will return some context about the desktop or kiosk device initiating the challenge such as ip address, location, user agent and custom data. This data can be shown to the user to help them decide if they want to approve or decline the challenge.

await authsignal.device.claimChallenge(
    challengeId: challengeId
)

Response

response

AuthsignalResponse<ClaimChallengeResponse>

Show properties

error

string

data

ClaimChallengeResponse

Show properties

ipAddress

string

required

The IP address of the device which initiated the challenge.

userAgent

string

required

The user agent of the device which initiated the challenge.

Updating a challenge

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

await authsignal.device.updateChallenge(
    challengeId: challengeId,
    approved: true
)

Response

response

AuthsignalResponse<boolean>

Show properties

error

string

data

boolean

True if the device challenge was successfully updated.

Verifying a device

Verify that the device has valid credentials.

await authsignal.device.verify()

Response

response

AuthsignalResponse<VerifyDeviceResponse>

Show properties

error

string

data

VerifyDeviceResponse

Show properties

token

string

required

A token which can be used for server-side validation.

userId

string

required

The user ID of the user that the device credential belongs to.

userAuthenticatorId

string

required

The user authenticator ID that the device credential belongs to.

username

string

The username of the user that the device credential belongs to.

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 device challenge).

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

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

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

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

val signature = authsignal.device.startSigning()

val cryptoObject = CryptoObject(signature)

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

biometricPrompt.authenticate(promptInfo, cryptoObject);

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.device.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.

await authsignal.email.enroll(email: "jane@authsignal.com")

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

string

The user’s email address.

Response

response

AuthsignalResponse<void>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

Challenge email

Start an email OTP challenge by sending the user an email containing an OTP code.

await authsignal.email.challenge()

Response

response

AuthsignalResponse<void>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

Verify email

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

await authsignal.email.verify(code: "123456")

Parameters

code

string

The OTP code inputted by the user.

Response

response

AuthsignalResponse<VerifyResponse>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

data

VerifyResponse

Show properties

isVerified

boolean

required

True if the verification was successful.

token

string

A token which can be used for server-side validation.

failureReason

string

A structured code present if the verification failed due to user error. Possible values are: CODE_INVALID_OR_EXPIRED or MAX_ATTEMPTS_EXCEEDED.

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.

await authsignal.sms.enroll(phoneNumber: "+64271234567")

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>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

Challenge SMS

Start an SMS challenge by sending the user an SMS containing an OTP code.

await authsignal.sms.challenge()

Response

response

AuthsignalResponse<void>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

Verify SMS

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

await authsignal.sms.verify(code: "123456")

Parameters

code

string

The OTP code inputted by the user.

Response

response

AuthsignalResponse<VerifyResponse>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

data

VerifyResponse

Show properties

isVerified

boolean

required

True if the verification was successful.

token

string

A token which can be used for server-side validation.

failureReason

string

A structured code present if the verification failed due to user error. Possible values are: CODE_INVALID_OR_EXPIRED or MAX_ATTEMPTS_EXCEEDED.

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.

let response await authsignal.totp.enroll()

if let data = response.data {
    let uri = data.uri // Convert to QR code
    let secret = data.secret // Can be entered manually
}

Response

response

AuthsignalResponse<EnrollTotpResponse>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

data

EnrollTotpResponse

Show properties

uri

string

required

A TOTP URI which can be converted into a QR code and presented to the user to scan with their authenticator app.

secret

string

required

The raw TOTP secret which can be presented to the user as a fallback option if they wish to enter a code manually instead of scanning a QR code.

Verify TOTP

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

await authsignal.totp.verify(code: "123456")

Parameters

code

string

The OTP code inputted by the user.

Response

response

AuthsignalResponse<VerifyResponse>

Show properties

error

string

An unstructured error description present if the SDK call encountered an error.

data

VerifyResponse

Show properties

isVerified

boolean

required

True if the verification was successful.

token

string

A token which can be used for server-side validation.

failureReason

string

A structured code present if the verification failed due to user error. Possible values are: CODE_INVALID_OR_EXPIRED or MAX_ATTEMPTS_EXCEEDED.

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).

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
};

const response = await authsignal.track(request);

const token = response.token;

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.

authsignal.setToken("eyJhbGciOiJ...")

// Send the user an email OTP code
// You can call this multiple times via a 'resend' button
await authsignal.email.challenge()

// Verify the inputted code matches the original code
let response = await authsignal.email.verify(code: "123456")

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.

Server

Client

​Requirements

​Installation

​Cocoapods

​Swift Package Manager

​Cocoapods

​Swift Package Manager

​Initialization

​Passkeys

​Prerequisites

​Creating a passkey

​Parameters

​Response

​Using a passkey

​Parameters

​Response

​Passkey autofill (iOS)

​Cancelling a request (iOS)

​Push

​Adding a credential

​Parameters

​Response

​Removing a credential

​Response

​Getting a challenge

​Response

​Updating a challenge

​Response

​Requiring user authentication (Android)

​Device

​Adding a credential

​Parameters

​Response

​Removing a credential

​Response

​Getting a challenge

​Response

​Claiming a challenge

​Response

​Updating a challenge

​Response

​Verifying a device

​Response

​Requiring user authentication (Android)

​Email OTP

​Enroll email

​Parameters

​Response

​Challenge email

​Response

​Verify email

​Parameters

​Response

​SMS OTP

​Enroll SMS

​Parameters

​Response

​Challenge SMS

​Response

​Verify SMS

​Parameters

​Response

​Authenticator app (TOTP)

​Enroll TOTP

​Response

​Verify TOTP

​Parameters

​Response

​Setting a token

​Error handling

​Error codes

Requirements

Installation

Cocoapods

Swift Package Manager

Cocoapods

Swift Package Manager

Initialization

Passkeys

Prerequisites

Creating a passkey

Parameters

Response

Using a passkey

Parameters

Response

Passkey autofill (iOS)

Cancelling a request (iOS)

Push

Adding a credential

Parameters

Response

Removing a credential

Response

Getting a challenge

Response

Updating a challenge

Response

Requiring user authentication (Android)

Device

Adding a credential

Parameters

Response

Removing a credential

Response

Getting a challenge

Response

Claiming a challenge

Response

Updating a challenge

Response

Verifying a device

Response

Requiring user authentication (Android)

Email OTP

Enroll email

Parameters

Response

Challenge email

Response

Verify email

Parameters

Response

SMS OTP

Enroll SMS

Parameters

Response

Challenge SMS

Response

Verify SMS

Parameters

Response

Authenticator app (TOTP)

Enroll TOTP

Response

Verify TOTP

Parameters

Response

Setting a token

Error handling

Error codes