Skip to content

Device Push & Mobile App

Turn your users' phones into a trusted authenticator — approve a sign-in, scan to log in on a laptop, or cryptographically sign exactly what they're authorizing.

What it is

HelixIAM provides a phone-as-authenticator factor: an enrolled mobile device becomes a strong, hardware-backed credential. It supports push approval, cross-device QR login, and transaction signing — and you can ship it inside your own branded app using the mobile SDK.

Capabilities

Hardware-key device enrolment

A device enrols with hardware-key attestation, binding the authenticator to the phone's secure hardware. This proves the credential lives on a genuine, untampered device before it is trusted.

Cross-device QR login

When a user signs in on a browser, Helix can present a QR code. Scanning it with the enrolled phone confirms the session — letting users authenticate on a laptop or shared screen using the device in their pocket.

Push approval with number matching

Helix sends a push notification to the enrolled device (over FCM for Android or APNs for Apple). To approve, the user must enter or tap the number shown in the browser — number matching. This defeats "push fatigue" and accidental approvals, because a blind tap is no longer enough.

Number matching stops push-bombing

Plain "approve/deny" prompts can be spammed until a user taps yes. Requiring the user to match the number displayed in the browser ensures the person approving is the person actually signing in.

Transaction signing (WYSIWYS)

For high-value actions, Helix supports transaction signing with dynamic linking — what you see is what you sign (WYSIWYS). The exact details of the action (for example, payee and amount) are shown on the device and cryptographically bound to the approval, so the user signs precisely what was requested and nothing can be altered in transit.

How it works

  1. The user enrols their device, which attests with its hardware key.
  2. At sign-in (or step-up), Helix sends a push, presents a QR code, or requests a transaction signature.
  3. The user confirms on the device — matching a number, scanning a code, or reviewing and signing a transaction.
  4. Helix verifies the response and completes the factor.

Build your own authenticator app

A mobile SDK is available to embed enrolment, push approval, QR login, and transaction signing into a fully branded authenticator app — so the experience carries your name, not a generic one.

Watch: set up the authenticator app

37 seconds, no sound. Check push delivery, switch the authenticator app on, set its limits and open the device list. Recorded on the current release.

In the console

Device push has three places in the console: the realm's Authenticator app page (what a phone must prove and how push sign-in behaves), the Authentication page (where the step sits in a flow), and Push delivery under Operations (how requests reach the phones).

  1. Check the push route under Operations → Push delivery (master console only). It shows the Delivery route (FCM project, APNs key, relay), the app attestation lists and Send a test notification. The values come from the server configuration or Helm chart and apply to every realm; they cannot be edited in the console.
  2. Open Authenticator app and turn on Use the authenticator app in this realm. The confirm dialog Ask every user to add a phone? warns that every user without a phone is asked to add one at their next sign-in (postponed for Days to set it up). Set Allowed platforms, Phone check when it is added, Rooted or jailbroken phones and the Push sign-in limits, then click Save.
  3. For phone sign-in without a password, turn on Sign in with the phone, without a password on the same page, then choose Phone approval (passwordless) or Scan QR code with the phone under First step on the Authentication page.
  4. For a second factor or step-up, add Push Approval to a stage with + method on the Authentication page.
  5. Users add their phone in the authenticator app at their next sign-in. The app registers its own push token; there is no console step for it. A user's phones are listed on the user's Devices tab and on the Devices page.

The Push tab on Notifications configures the realm's own notification messages, not the Authenticator app's sign-in requests.

Over the API

Device push spans two surfaces. The device-facing ceremonies (enrol, approve, QR confirm, sign) are protocol endpoints the authenticator app calls — no admin session, driven by the mobile SDK. Registering and listing a user's push tokens is on the admin surface (session + CSRF). The admin examples assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List a user's push tokens (admin)

userId is a required query parameter.

curl -s -b cookies.txt \
  "$HELIX_URL/admin/realms/$REALM/messaging/push-tokens?userId=c1a848b2-cf68-45d5-85d1-97101cb702a8"
[]

Register a push token (admin)

A device can only receive approvals once its FCM/APNs token is registered. The body is {userId, platform, token}.

# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "userId": "c1a848b2-cf68-45d5-85d1-97101cb702a8",
        "platform": "APNS",
        "token": "a1b2c3…device-push-token"
      }' \
  "$HELIX_URL/admin/realms/$REALM/messaging/push-tokens"

Device-facing endpoints (mobile SDK / protocol)

These are called by the enrolled authenticator app, not by an admin script. The id is the pending challenge identifier surfaced in the browser flow.

Method & path Purpose
POST /device/enroll/start · POST /device/enroll Begin / complete hardware-attested device enrolment
GET /push/{id} · POST /push/{id}/approve · POST /push/{id}/deny Read / approve (with number match) / deny a push challenge
GET /qr/{id} · POST /qr/{id}/confirm Read / confirm a cross-device QR login
GET /tx/{id} · POST /tx/{id}/sign · POST /tx/{id}/consume Read / sign (WYSIWYS) / consume a transaction-signing request

Number matching is enforced in the approval body

A push approval carries the selectedNumber the user tapped, so a blind approve/deny is not enough — see the ApproveRequest schema in the API reference.

Full endpoint set (admin surface)

Method & path (under /admin/realms/{realm}) Purpose
GET /messaging/push-tokens?userId=… · POST /messaging/push-tokens List / register a user's device push tokens
GET /flows/{alias} · PUT /flows/{alias} Read / save the flow that presents the push (or QR / tx-signing) step
GET · PUT /messaging/providers Configure the realm's notification providers (SMS, email, push messages)

See also