Authenticator Apps (TOTP)

Descope supports validating sign-up and sign-ins via Authenticator Applications which provide a Time-based One-time Password (TOTP). Google Authenticator, Microsoft Authenticator, and Authy are examples of authenticator apps. Descope generates the required QR code or key (also called a secret or seed) in order to configure new a new Authenticator.

Authenticator Apps (TOTP) with Flows

This guide will walk you through integrating TOTP Authenticator Apps into your Descope Flows. TOTP (Time-Based One-Time Password) adds an extra layer of security by requiring users to enter a code generated by an authenticator app.

Flow Actions

When using TOTP, the following actions are available:

• Sign Up / TOTP - Verifies the TOTP code and signs the user up if they do not exist.
• Sign In / TOTP - Verifies the TOTP code and signs the user in if they already exist; fails if they do not.
• Update User / TOTP - Links an authenticator app to an existing user, so they can use it as an authentication method in the future.

How to Use TOTP Actions

These actions can be integrated into your application like any other Action.

This is an example of using the Sign Up or In / TOTP action in a flow:

To verify and set up an authenticator app using TOTP, you'll need to scan the QR code automatically created from the action, and verify the code with Descope.

Flow Screens

There's not much you need to handle in flow screens when using TOTP. However, you can develop your own screens and customize how users set up their authenticator apps. Descope provides multiple methods for TOTP setup:

QR Code Setup

The most common method for setting up TOTP is by scanning a QR code. When using TOTP actions in your flow, Descope automatically generates a QR code that users can scan with their authenticator app.

You can customize the QR code display in your flow screens using the TOTP QR Code action. This allows you to control the placement and styling of the QR code in your custom screens.

To set up TOTP using a QR code:

1. Open your authenticator app (Google Authenticator, Microsoft Authenticator, Authy, etc.)
2. Select the option to add a new account or scan a QR code
3. Point your device's camera at the QR code displayed in the flow screen
4. The authenticator app will automatically configure the account and start generating codes

Provision URL

To enhance the user experience, especially for mobile users, you can add a Provision URL alongside the TOTP QR code on the setup screen. This URL is a clickable link that redirects users directly to their authenticator app, eliminating the need to manually open the app and scan the QR code.

When tapped, the device recognizes the URL scheme and automatically opens a supported authenticator app (such as Google Authenticator, Microsoft Authenticator, or Authy) with the TOTP configuration ready to be added.

Manual TOTP Setup

In some cases, users may prefer to manually enter the TOTP key into their authenticator app instead of scanning the QR code. This can be useful when:

• The QR code cannot be scanned (e.g., camera issues or accessibility needs)
• The authenticator app doesn't support QR code scanning
• The user is using a mobile device and prefers to enter the key manually

To enable manual setup, you can display the TOTP key to users in your flow screen using the {{totp.key}} variable. This will show the secret key (also called a seed) that users can copy and paste into their authenticator app.

How to Delete TOTP for users

Descoper can remove or delete TOTP for a user who has signed up with it. Once the user is enabled with the TOTP authentication method, their record appears in the user management console.

Descope provides an option to clear or reset TOTP for that user if necessary. This can be done by selecting the user record and choosing one of two methods.

One method is to click on the three dots on the right and select Delete TOTP Seed. Alternatively, you can click Delete TOTP Seed at the top of the table.

This allows you to reset TOTP for users who have registered with TOTP auth method.

Error Handling

Error handling is handled like any other action. You can refer to our Flow Error Handling guide for more details.