A push notification displayed on a mobile device.

This method uses the Device SDK to sign a challenge with the user’s device credentials.

Device auth can be used to send a push notification to a user’s mobile app. This enables users to approve login attempts with a simple tap on their mobile device.

When a login is attempted, the system creates a challenge that can only be verified using the private key on the user’s registered device, ensuring secure authentication.

​
Prerequisites

​
Sequence

​
Implementation

​
1. Initiate a device challenge

1.1 Track action (Backend)

When a user performs an action that requires authentication, your backend should track the action. You can use our Server SDK or Server API to track the action.

1.2 Start push challenge (Frontend)

Use our browser SDK or Client API to initiate a push challenge. This will trigger the push notification to be sent via the configured settings.

Note this model assumes push notification delivery is not guaranteed or required. I.e., Even if a push notification is not delivered, it is recommended that you present a message to the user on your frontend to inform them that the challenge has been initiated and to open their mobile app.

1.3. Poll for the challenge result (Frontend)

Poll for the challenge result using our browser SDK or API. We recommend polling every 1-2 seconds.

const response = await authsignal.push.verify({
  challengeId: "challenge_id",
});

Poll states:

1

Declined

isConsumed is true, isVerified is false

The challenge has been declined by a user. Show an error message to the user and provide a way to retry the challenge.

{
  "isConsumed": true,
  "isVerified": false
}
2

Verified

isConsumed is true, isVerified is true and an accessToken is returned.

The challenge has been verified by a user. Show a success message to the user and proceed with the next step.

{
  "isConsumed": true,
  "isVerified": true,
  "accessToken": "access_token"
}

​
2. Present dialog for user to approve/reject (Mobile)

When the app is foregrounded, use the mobile sdk getChallenge method to check if there is a challenge. If there is a challenge, present a dialog to allow the user to approve or decline the challenge.

const response = await authsignal.device.getChallenge();

​
3. Approve or decline the challenge (Mobile)

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

const response = await authsignal.device.updateChallenge({
  challengeId: "challenge_id",
  approve: true,
});

​
4. Validate the challenge (Backend)

Once the challenge is approved, the challenge verify api being polled in step 1.3 will return an accessToken that should be passed to your backend to validate the challenge prior to completing the authentication flow.

If the challenge is declined, the api will return isConsumed as true and isVerified as false. The UI should be updated to reflect that the challenge was declined.