QR code verification

QR code verification uses app credentials to enable cross-device authentication. This method leverages public key cryptography where private keys are securely stored on the user’s device. The Mobile SDK is used for two key steps:

Registering a mobile device for QR code verification by adding a credential. This step creates a new public/private key pair.
Responding to an authentication request by approving or rejecting a challenge. This step uses the device’s private key to sign a message which is verified on the server using the public key.

Use cases

Log into a desktop or web application from an application that is typically used on mobile
Identify a user on a kiosk in a quick service restaurant (QSR) to load loyalty programs, rewards and offers
Log into an application running on a TV
Complete a payment via a terminal

Sequence diagram

The general flow for QR code verification is as follows:

Generate a challenge
Display the QR code to the user
Wait for the user to scan and respond on their mobile device
Handle the authentication result (approved/rejected)

Portal setup

Enable QR code verification for your tenant.

SDK setup

Server SDK

Initialize the SDK using your Server API secret key from the API keys page and the API URL for your region.

import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({
  apiSecretKey: "YOUR_SECRET_KEY",
  apiUrl: "YOUR_API_URL",
});

using Authsignal;

var authsignal = new AuthsignalClient(
    apiSecretKey: "YOUR_SECRET_KEY",
    apiUrl: "YOUR_API_URL"
);

import com.authsignal.AuthsignalClient;

AuthsignalClient authsignal = new AuthsignalClient(
    "YOUR_SECRET_KEY",
    "YOUR_API_URL"
);

require 'authsignal'

Authsignal.setup do |config|
    config.api_secret_key = ENV["YOUR_SECRET_KEY"]
    config.api_url = "YOUR_API_URL"
end

from authsignal.client import AuthsignalClient

authsignal = AuthsignalClient(
    api_secret_key="YOUR_SECRET_KEY",
    api_url="YOUR_API_URL"
)

Authsignal::setApiSecretKey("YOUR_SECRET_KEY");
Authsignal::setApiUrl("YOUR_API_URL");

import "github.com/authsignal/authsignalgo/v2/client"

client := NewAuthsignalClient(
    "YOUR_SECRET_KEY",
    "YOUR_API_URL",
)

Web and Mobile SDKs

The Web SDK is used to initiate the challenge in a browser by generating a QR code. The Mobile SDK is used to respond to the challenge in a mobile app by scanning the QR code. Initialize both SDKs using your tenant ID from the API keys page and your API URL.

import { Authsignal } from "@authsignal/browser";

const authsignal = new Authsignal({
  tenantId: "YOUR_TENANT_ID",
  baseUrl: "YOUR_API_URL",
});

import Authsignal

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

import com.authsignal.Authsignal

val authsignal = Authsignal(
    tenantID = "YOUR_TENANT_ID",
    baseURL = "YOUR_API_URL",
)

import { Authsignal } from "react-native-authsignal";

const authsignal = new Authsignal({
  tenantID: "YOUR_TENANT_ID",
  baseURL: "YOUR_API_URL",
});

import 'package:authsignal_flutter/authsignal_flutter.dart';

final authsignal = Authsignal(
    "YOUR_TENANT_ID",
    baseURL: "YOUR_API_URL"
);

Enrollment

Scenario - Enroll users for QR code verification in your mobile app so it can be used as a method for authenticating on another device.

1. Generate enrollment token

In your backend, track an action for a user (e.g. “addAuthenticator”) to generate a short-lived token.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "addAuthenticator",
  attributes: {
    scope: "add:authenticators",
  },
};

const response = await authsignal.track(request);

const token = response.token;

var request = new TrackRequest(
    UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    Action: "addAuthenticator",
    Attributes: new TrackAttributes(
        Scope: "add:authenticators",
    )
);

var response = await authsignal.Track(request);

var token = response.Token;

TrackRequest request = new TrackRequest();
request.userId = "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833";
request.action = "addAuthenticator";
request.attributes = new TrackAttributes();
request.attributes.scope = "add:authenticators";

TrackResponse response = authsignal.track(request).get();

String token = response.token;

response = Authsignal.track({
  user_id: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "addAuthenticator",
  attributes: {
    scope: "add:authenticators",
  }
})

token = response[:token]

response = authsignal.track(
    user_id="dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    action="addAuthenticator",
    attributes={
        "scope": "add:authenticators",
    }
)

token = response["token"]

$response = Authsignal::track([
    'userId' => "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    'action' => "addAuthenticator",
    'attributes' => [
        'scope' => "add:authenticators",
    ]
]);

$token = $response["token"]

response, err := client.Track(
    TrackRequest{
        UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
        Action: "addAuthenticator",
        Attributes: &TrackAttributes{
            scope: "add:authenticators",
        },
    },
)

token := response.Token

This token will be used to authorize enrolling a new authentication method on their mobile device. The add:authenticators scope is required to enroll a new authentication factor for an existing user. This scope should only be used when the user is in an already authenticated state. For more information on using scopes safely refer to our documentation on authenticator binding.

2. Add credential

Use the token obtained in step 1 to enroll a new device credential for the user in the mobile app.

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

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

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

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

Authentication

Scenario - Let users scan a QR code with their mobile app to authenticate on another device.

1. Track action (optional)

You may optionally track an action from your backend if you want to create a QR code challenge that can only be completed by a specific user or run rules on the action for adaptive MFA. If you want to start a QR code challenge that can be claimed and completed by any user, skip to step 2. Track an action from your backend using our Server SDK.

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

const response = await authsignal.track(request);

if (response.state === "CHALLENGE_REQUIRED") {
  // Obtain token to present challenge
  const token = response.token;
}

var request = new TrackRequest(
    UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    Action: "signIn"
);

var response = await authsignal.Track(request);

if (response.State == UserActionState.CHALLENGE_REQUIRED)
{
    // Obtain token to present challenge
    var token = response.Token;
}

TrackRequest request = new TrackRequest();
request.userId = "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833";
request.action = "signIn";

TrackResponse response = authsignal.track(request).get();

if (response.state.equals(UserActionState.CHALLENGE_REQUIRED)) {
    // Obtain token to present challenge
    String token = response.token;
}

response = Authsignal.track({
  user_id: 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
  action: 'signIn'
})

case response[:state]
when "CHALLENGE_REQUIRED"
  # Obtain token to present challenge
  token = response[:token]
end

response = authsignal.track(
    user_id="dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    action="signIn"
)

if response["state"] == "CHALLENGE_REQUIRED":
    # Obtain token to present challenge
    token = response["token"]

$response = $authsignal->track([
    'userId' => 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
    'action' => 'signIn'
]);

switch ($response['state']) {
    case 'CHALLENGE_REQUIRED':
        // Obtain token to present challenge
        $token = $response['token'];
}

response, err := client.Track(
    TrackRequest{
        UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
        Action: "signIn",
    },
)

switch response.State {
case "CHALLENGE_REQUIRED":
    // Obtain token to present challenge
    token := response.Token
}

Return the token to your frontend and call the Web SDK’s setToken method.

authsignal.setToken(response.token);

When creating a QR code challenge after tracking an action, the custom data and action code must be provided in the track request and cannot be overridden in the challenge request from the frontend.

2. Present QR code

Use our Web SDK to initiate a QR code challenge. Initiate QR code challenge Use the qrCode.challenge() method to initiate a challenge. The SDK will handle all the complexity of managing the challenge lifecycle, including automatic refreshing and state updates. By default the SDK will use WebSocket connections. If your environment does not support WebSockets, you can fall back to polling using REST API calls by setting polling to true.

const { data } = await authsignal.qrCode.challenge({
  action: "signIn",
  onStateChange: (state, token) => {
    switch (state) {
      case "claimed":
        // User has scanned the QR code - blur/hide it
        console.log("QR code claimed by user");
        break;
      case "approved":
        // Challenge approved - validate the token on your backend
        if (token) {
          validateChallengeOnBackend(token);
          // Continue with the application flow
        }
        break;
      case "rejected":
        // Challenge rejected - show error and offer retry
        console.log("Challenge rejected by user");
        break;
    }
  },
  onRefresh: ({ challengeId, expiresAt }) => {
    // Update your QR code display with the new challengeId
    updateQRCode(challengeId);
  },
  // Optional: Add context that will be shown on the user's device. Only available for anonymous challenges.
  custom: {
    deviceInfo: "Terminal A",
  },
  refreshInterval: 540000, // 9 minutes (default)
  polling: false, // Use WebSocket for real-time updates (default)
});

// Display the QR code using the challengeId
if (data?.challengeId) {
  displayQRCode(data.challengeId);
}

State changes

Initial state

After calling qrCode.challenge(), the QR code is ready to be scanned. Display it to the user.

Claimed

When onStateChange is called with state: "claimed", the user has scanned the QR code. You can use this state change to indicate progress in your UI.

Approved

When onStateChange is called with state: "approved" and a token, the user has approved the challenge. Pass the token to your backend for validation.

Rejected

When onStateChange is called with state: "rejected", the user has declined the challenge. Show an error message and provide a way to retry.

Refresh a challenge (optional) If you need to manually refresh a challenge you can use the qrCode.refresh() method:

// Manually refresh with optional updated context
await authsignal.qrCode.refresh({
  custom: {
    deviceInfo: "Terminal B",
  },
});

This must be called after qrCode.challenge() method has been called. The original callbacks will be used with the new challenge.

3. Scan QR code

Once the user scans the QR code, use the mobile sdk Claim Challenge method to set the user attempting to complete the challenge. The Claim Challenge method will return some context about the desktop or kiosk 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.

To display custom data points passed into the initial track request, mark the relevant custom data points as public.

await authsignal.qr.claimChallenge(
    challengeId: challengeId
)

authsignal.qr.claimChallenge(
    challengeId = challengeId
)

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

await authsignal.qr.claimChallenge(
    challengeId,
);

4. Approve or decline the challenge

Present a dialog to allow the user to review the challenge context and approve or decline the challenge by calling the mobile sdk Update Challenge method.

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

5. Complete authentication

Once the challenge is approved, the onStateChange callback will return a token that should be passed to your backend to validate the challenge for the action and complete the authentication flow.

const response = await authsignal.validateChallenge({
  action: "signIn",
  token: "eyJhbGciOiJIUzI....",
});

if (response.state === "CHALLENGE_SUCCEEDED") {
  // User completed challenge successfully
}

var request = new ValidateChallengeRequest(
    Action: "signIn",
    Token: "eyJhbGciOiJIUzI...."
);

var response = await authsignal.ValidateChallenge(request);

if (response.State == UserActionState.CHALLENGE_SUCCEEDED) {
    // User completed challenge successfully
}

ValidateChallengeRequest request = new ValidateChallengeRequest();
request.action = "signIn";
request.token = "eyJhbGciOiJIUzI....";

ValidateChallengeResponse response = authsignal.validateChallenge(request).get();

if (response.state == UserActionState.CHALLENGE_SUCCEEDED) {
   // User completed challenge successfully
}

response = Authsignal.validate_challenge(action: "signIn", token: "eyJhbGciOiJIUzI....")

if response[:state] == "CHALLENGE_SUCCEEDED"
  # User completed challenge successfully
end

response = authsignal.validate_challenge(action="signIn", token="eyJhbGciOiJIUzI....")

if response["state"] == "CHALLENGE_SUCCEEDED":
    # User completed challenge successfully

$response = Authsignal::validateChallenge(action: "signIn", token: "eyJhbGciOiJIUzI....");

if ($response["state"] === "CHALLENGE_SUCCEEDED") {
    # User completed challenge successfully
}

response, err := client.ValidateChallenge(
    ValidateChallengeRequest{
        Action: "signIn",
        Token: "eyJhbGciOiJ...",
    },
)

if response.State == "CHALLENGE_SUCCEEDED" {
    // User completed challenge successfully
}

Next steps

Passkeys - Offer the most secure and user-friendly passwordless authentication

​Use cases

​Sequence diagram

​Portal setup

​SDK setup

​Server SDK

​Web and Mobile SDKs

​Enrollment

​1. Generate enrollment token

​2. Add credential

​Authentication

​1. Track action (optional)

​2. Present QR code

​3. Scan QR code

​4. Approve or decline the challenge

​5. Complete authentication

​Next steps

Use cases

Sequence diagram

Portal setup

SDK setup

Server SDK

Web and Mobile SDKs

Enrollment

1. Generate enrollment token

2. Add credential

Authentication

1. Track action (optional)

2. Present QR code

3. Scan QR code

4. Approve or decline the challenge

5. Complete authentication

Next steps