Blog/tutorials

# Ratelimiting OTP endpoints

Without ratelimiting OTP endpoints you are exposed to brute force attacks, learn how to secure the endpoints using a ratelimiter.

Written by

Lê Sỹ Cường

Published on

Jul 18, 2024

## Understanding OTP

A One-Time Password (OTP) is a unique code valid for only one login session or transaction. It adds an extra layer of security by preventing fraudulent access to your accounts, even if someone else knows your password. You've likely encountered OTPs many times. For instance, when logging into your bank account from a new device, you may receive an OTP via SMS or email, which you must enter to verify your identity. Another typical example is the login flow, where instead of entering a password, an OTP is sent to your email.

Without ratelimiting, an attacker could try several OTPs in quick succession in a so-called 'brute force attack' to find the right one to gain access to an account.

By limiting the number of OTP attempts within a specific timeframe, it becomes practically impossible for an attacker to guess the right OTP before it expires.

## Implementing ratelimiting

### Prerequisites

- Unkey account
- Unkey root key with permissions `create_namespace`, `limit`

If you prefer, you can use our example here and skip the entire tutorial below. Also, if you want to see it live, you can see an implementation below using Unkey and Resend here

Before we begin with the tutorial, it should be stated that OTP implementations will have two separate requests: sending the OTP via email or SMS and verifying the request.

Let’s start with the sending of an OTP. Below is an insecure OTP implementation with a fake email that sends a random 6-digit code to the user via a next.js server action.

    1"use server";
    2import { randomInt } from "crypto";
    3
    4export async function sendOTP(formData: FormData) {
    5  try {
    6    const email = formData.get("email") as string | null;
    7    if (!email) {
    8      return {
    9        success: false,
    10        error: "Email was not supplied, please try again",
    11        statusCode: 400,
    12      };
    13    }
    14    const otp = randomInt(100000, 999999).toString();
    15
    16    const { data, error } = await emails.send({
    17      from: "james@unkey.com",
    18      to: email,
    19      subject: "OTP code",
    20      text: `Your OTP code is ${otp}`
    21    });
    22    // handled error
    23    if (error) {
    24      console.error(error);
    25      return { success: false, error: "Failed to send email", statusCode: 500 };
    26    }
    27    return {
    28      success: true,
    29      statusCode: 201,
    30    };
    31    //catch
    32  } catch (e) {
    33    return { success: false, error: "Failed to send email", statusCode: 500 };
    34  }
    35}

### Adding ratelimiting to sending an OTP

First, you’ll need to install the `@unkey/ratelimit` package to your project and then add the following imports.

    1import { Ratelimit } from "@unkey/ratelimit";
    2import { headers } from "next/headers";

We will use the headers to retrieve the IP of the requester and use that as an identifier to limit against. Now we need to configure the ratelimiter

    1const unkey = new Ratelimit({
    2  rootKey: process.env.UNKEY_ROOT_KEY,
    3  namespace: "otp-send",
    4  limit: 2,
    5  duration: "60s",
    6})
    7
    8export async function sendOTP(formData: FormData) {
    9  // sending OTP logic

The above code will configure a new namespace named `otp-send` if it doesn’t exist and limit the requests to two per minute. Of course, any number of attempts, but two emails per minute should suffice for the end user.

Now that we have our ratelimiter configured, we can modify the request to first retrieve the IP address; this will check for both the forwarded IP address and the real IP from the headers. We will use the forwarded IP first and fall back to the real IP.

    1export async function sendOTP(formData: FormData) {
    2  try {
    3    // check for forwarded
    4    let forwardedIP = headers().get("x-forwarded-for");
    5    // check for real-ip
    6    let realIP = headers().get("x-real-ip");
    7    if(forwardedIP){
    8      forwardedIP = forwardedIP.split(/, /)[0]
    9    }
    10    if (realIP) realIP = realIP.trim();
    11    // sending logic below

Now we have access to an identifier, and we can run our rate limit against it. Add the following code before checking if the user has provided an email.

    1const { success, reset } = await unkey.limit(
    2      forwardedIP || realIP || "no-ip",
    3    );
    4    const millis = reset - Date.now();
    5    const timeToReset = Math.floor(millis / 1000);
    6		// if this is unsuccesful return a time to reset to the user so they know how long to wait
    7    if (!success) {
    8      return {
    9        success: false,
    10        error: `You can request a new code in ${timeToReset} seconds`,
    11        statusCode: 429,
    12      };
    13    }
    14
    15    const email = formData.get("email") as string | null;
    16    //shortened for tutorial.

You’ll notice that we check for `forwardedIP` and then the `realIP`, and finally, if nothing is available, we will use `no-ip` for the fallback. This endpoint is now protected; a user can send two requests per minute. Below is a demo of how you could present this to the user:

### Ratelimiting the OTP verification

The endpoint that verifies an OTP has more potential for brute force attacks; sending codes down with no restriction will give a bad actor plenty of time to try numerous codes to get the right one.

This is where the flexibility of ratelimiting for Unkey can come into play while it is similar to the above server action. For example

    1export async function verifyOTP(prevState: any, formData: FormData) {
    2  try {
    3    // check for forwarded
    4    let forwardedIP = headers().get("x-forwarded-for");
    5    // check for real-ip
    6    let realIP = headers().get("x-real-ip");
    7    if (forwardedIP) {
    8      forwardedIP.split(/, /)[0];
    9    }
    10    if (realIP) {
    11      realIP = realIP.trim();
    12    }
    13
    14    const code = formData.get("code") as string | null;
    15
    16    if (!code) {
    17      return {
    18        success: false,
    19        error: "Code was not supplied, please try again",
    20        statusCode: 400,
    21      };
    22    }
    23
    24    const { success, reset } = await unkey.limit(
    25      forwardedIP || realIP || "no-ip",
    26    );
    27    const millis = reset - Date.now();
    28    const timeToReset = Math.floor(millis / 1000);
    29
    30    if (!success) {
    31      return {
    32        success: false,
    33        error: `You have been rate limited, please wait ${timeToReset} seconds and try entering a new code`,
    34        statusCode: 429,
    35      };
    36    }
    37    // Handle verification of your OTP

You can set the limits and namespace to be different, allowing you to be more restrictive and keep all your analytical data separated, for example.

    1const unkey = new Ratelimit({
    2  rootKey: process.env.UNKEY_ROOT_KEY!,
    3  namespace: "otp-verify",
    4  limit: 2,
    5  duration: "30s",
    6});

This operation will allow a user to try twice every 30 seconds before it ratelimits the operation for the IP. Below is an example of how this could look in your application from the example code.

## Best Practices in Rate Limiting OTP

Implementing rate limiting is one thing, but ratelimiting effectively requires following best practices. Here are some tips:

- Set reasonable limits: Your users should have enough attempts to enter their OTP correctly, but not so many that an attacker could guess.
- Educate your users: Make sure your users understand why they're being blocked from logging in after too many attempts and how long they have to wait before they can try again.
- Monitor and adjust: Regularly review your system's performance and adapt your limits as needed.

These practices enhance the security and efficiency of OTPs while maintaining a positive user experience.

You can read more about Unkey’s Ratelimiting our documentation, you can see the demo of this in action and test what happens when you go over limits.

Written by

Lê Sỹ Cường

Published on

Jul 18, 2024

Contents

- Implementing ratelimiting
- Prerequisites
- Adding ratelimiting to sending an OTP
- Ratelimiting the OTP verification
- Best Practices in Rate Limiting OTP

Suggested

Vncod — Hành trình định nghĩa lại tiêu chuẩn vận hành Game

Mar 26, 2026

How to ratelimit public pages

Dec 11, 2025

Building a flow editor

Dec 02, 2025

## Sẵn sàng bứt phá doanh thu.
Bắt đầu ngay hôm nay.

Liên hệ với chúng tôi
Server Game

Hỗ trợ cài đặt trọn gói. Cam kết vận hành ổn định 24/7.

We value your privacy
This site uses cookies to improve your browsing experience, analyze site traffic, and show personalized content.