Time-based One-Time Password (TOTP): What is it?

Time-based One-Time Password (TOTP): What is it?

How it works and with examples written in NodeJS

A time-based one-time password (TOTP) is a one-time password generated based on the current time and a shared secret key. This method of authentication is used in addition to a username/email and password for increased security. TOTP is used in situations where it is not feasible to use hardware-based tokens, such as when logging in from a public computer. TOTP is an open standard defined in RFC6238. This article will explain the basics you need to know about TOTP authentication as well as how to implement it in NodeJS applications. Let’s get started!

What is TOTP Authentication?

TOTP authentication is an authentication method using a time-based One-Time Password (OTP). Traditional login methods are made more secure by TOTP authentication because a user can only access an account for a limited period of time. Access will be prohibited if you try to log into an account outside of the limited time window. TOTP authentication is most frequently used for 2FA, software, and remote employee logins.

How does TOTP Authentication work?

A shared secret key and the current time are used to generate a new one-time-use password for TOTP authentication. The user then logs in or completes a login using this password (in the case of 2FA). Users are advised to enter the code as soon as it is generated because this password changes every 30 seconds. Users must enter a username, a code generated from the given time period, and —depending on the system requirement— a password in order to use TOTP authentication. In contrast to conventional login techniques, where users only need to remember their username and password, this requires more information from the user.

Because of its high level of security, TOTP authentication is being used more frequently. In the traditional authentication technique, it is simpler for hackers to access numerous accounts because users just need one username and password. However, users must enter a code produced from the selected time period during TOTP authentication, which adds an additional degree of protection. This implies that in order to log into several accounts, a user would require access to various devices.

How to implement TOTP in NodeJS?

There are a few things we need to do in order to implement TOTP authentication in NodeJS. In this section, we're going to use a package called speakeasy. Speakeasy distinguishes out from the other 2FA projects on GitHub because of how active it is. We're going to experiment with this package in a new project to simplify things.

Install Dependencies

Execute the following command start a new NodeJS project and install the Speakeasy package. Additionally, a package required for managing POST requests with a payload will be installed, along with Express.js.

npm init -y
npm install express body-parser speakeasy
npm install -D typescript @types/express @types/speakeasy

Ensure that an app.js file is created in the current project directory and that it contains the boilerplate content listed below.

import express, { Request, Response, NextFunction } from "express";
import * as bodyParser from "body-parser";
import { generateSecret, totp } from 'speakeasy';

export const app = express();

app.use(bodyParser.urlencoded({ extended: true }));

// generate a secret token to be saved in an application like Google Authenticator
app.post("/generate-secret", (request: Request, response: Response, next: NextFunction) => { });

// validate that the TOTP is valid for a given secret and is not expired
app.post("/validate-token", (request: Request, response: Response, next: NextFunction) => { });

app.listen(5000, () => {
    console.log("Listening at :5000");

Generate TOTP Secret

First, we need to generate a shared secret key. This key will be used to generate the one-time-use passwords by the authenticator app. The generated token can be made into a QR code which can be scanned by an authenticator app. typescript app.post("/generate-secret", (request: Request, response: Response, next: NextFunction) => { const {otpauth_url, base32} = generateSecret({ length: 20 }); saveSecretToDB(request.userId, base32); response.send({ "secret": base32 }); }); —or— Generating a QR code

By manually entering a key or scanning a QR code, users can add a page to which they authenticate using applications like the Google Authenticator. The latter is common and significantly quicker. We employ QRcode library to produce QR images. We can install the QRcode package by running npm install qrcode @types/qrcode

import * as QRCode from 'qrcode';

app.post("/generate-secret", (request: Request, response: Response, next: NextFunction) => {
    const {otpauth_url, base32} = generateSecret({ length: 20 });
    // How you store generated secret key varies by implementation
    saveSecretToDB(request.userId, base32);
    QRCode.toFileStream(response, otpauth_url);

Validate TOTP Secret

To validate a code provided by the user —which is generated by the authenticator app— typescript app.post("/validate-token", (request: Request, response: Response, next: NextFunction) => { // How you get the secret for first-time activation depends on the implementation const secret = request.body.secret || findSecretFromDB(request.userId); const isValid = totp.verify({ secret: secret, encoding: "base32", token: request.body.token, window: 0 }) // Depending on your implementation, the secret is probably already saved saveSecret(secret) response.send({ isValid }); });


TOTP authentication is an extra layer of security used in two-factor login methods. It creates a one-time-use password using a shared secret key and a predetermined amount of time. Due to its high level of security and simplicity of use, TOTP authentication is becoming more and more popular as an additional security measure.