QR code verification

Check out our end-to-end guide on how to implement app verification with QR codes.

Adding a credential

Adding a QR code 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.qr.addCredential(token: "eyJhbGciOiJ...")

authsignal.qr.addCredential(token = "eyJhbGciOiJ...")

await authsignal.qr.addCredential({ token: "eyJhbGciOiJ..." });

await authsignal.qr.addCredential("eyJhbGciOiJ...");

Parameters

string

A short-lived token obtained by tracking an action.

Response

AuthsignalResponse<AppCredential>

Show properties

string

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

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.

AppCredential | null

Show properties

string

required

The ID of the app credential.

string

required

The date and time the app credential was created.

string

required

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

Getting a credential

Get information about the QR code credential stored on the device, if one exists.

let response = await authsignal.qr.getCredential()

val response = authsignal.qr.getCredential()

const response = await authsignal.qr.getCredential();

final response = await authsignal.qr.getCredential();

Response

AuthsignalResponse<AppCredential>

Show properties

string

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

string

A formatted error code which may additionally be present if the SDK call encountered an error. Possible values are: invalid_credential when the credential exists on the device but has been removed from the server.

AppCredential

Show properties

string

required

The ID of the app credential.

string

required

The date and time the app credential was created.

string

The date and time the app credential was last used for authentication. Will be null if the credential has never been used.

string

required

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

Removing a credential

await authsignal.qr.removeCredential()

authsignal.qr.removeCredential()

await authsignal.qr.removeCredential();

await authsignal.qr.removeCredential();

Response

AuthsignalResponse<boolean>

Show properties

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.

boolean

True if the app credential was successfully removed.

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.qr.claimChallenge(
    challengeId: challengeId
)

authsignal.qr.claimChallenge(
    challengeId = challengeId
)

await authsignal.qr.claimChallenge({
  challengeId,
});

await authsignal.qr.claimChallenge(
    challengeId,
);

Response

AuthsignalResponse<ClaimChallengeResponse>

Show properties

string

ClaimChallengeResponse

Show properties

string

required

The IP address of the device which initiated the challenge.

string

required

The user agent of the device which initiated the challenge.

object

Action-scope custom data passed to the challenge. Only custom data points marked as public are returned.

object

Show properties

object

User-scope custom data for the user being challenged. Only custom data points marked as public are returned.

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.qr.updateChallenge(
    challengeId: challengeId,
    approved: true
)

authsignal.qr.updateChallenge(
    challengeId = challengeId,
    approved = true
)

await authsignal.qr.updateChallenge({
  challengeId,
  approved: true,
});

await authsignal.qr.updateChallenge(
    challengeId,
    true,
);

Response

AuthsignalResponse<boolean>

Show properties

string

boolean

True if the device challenge was successfully updated.

Requiring user authentication

When adding a credential for QR code verification, it is possible to require that the user authenticate via their OS biometrics or PIN whenever they access the credential (e.g. when approving or rejecting a challenge).

iOS

To require user authentication on iOS, set the userPresenceRequired flag to true when adding the credential.

await authsignal.qr.addCredential(
    token: token,
    userPresenceRequired: true
)

This is all that’s needed - iOS will automatically handle displaying the biometrics or PIN prompt when updating a challenge or verifying a device.

Android

To require user authentication on Android, set the userAuthenticationRequired flag to true when adding the credential.

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

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

authsignal.qr.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.qr.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.qr.updateChallenge(
        challengeId = challengeId,
        approved = true,
        signer = signer
    )
}

Server

Client

Call Connect

QR code verification

Adding a credential

Parameters

Response

Getting a credential

Response

Removing a credential

Response

Claiming a challenge

Response

Updating a challenge

Response

Requiring user authentication

iOS

Android

​Adding a credential

​Parameters

​Response

​Getting a credential

​Response

​Removing a credential

​Response

​Claiming a challenge

​Response

​Updating a challenge

​Response

​Requiring user authentication

​iOS

​Android

Adding a credential

Parameters

Response

Getting a credential

Response

Removing a credential

Response

Claiming a challenge

Response

Updating a challenge

Response

Requiring user authentication

iOS

Android