Skip to main content

​
Overview

The OTPConfig interface defines settings for one-time password (OTP) generation, validation, and delivery. 
interface OTPConfig {
  length?: number
  expiresIn?: number
  maxAttempts?: number
  messageTemplate?: (otp: string, appName?: string) => string
}

​
Fields

​
length
number
default:"6"
The number of digits in the generated OTP code.
length: 6 // Generates codes like 123456
Valid range is 4-10 digits. Shorter codes are easier to type but less secure. Six digits is the industry standard.
​
expiresIn
number
default:"300"
OTP expiration time in seconds.
expiresIn: 600 // 10 minutes
expiresIn: 300 // 5 minutes (default)
expiresIn: 900 // 15 minutes
Balance security with user experience. Shorter expiration times are more secure but may frustrate users who take longer to enter the code.
​
maxAttempts
number
default:"3"
Maximum number of verification attempts allowed before the OTP becomes invalid.
maxAttempts: 5 // Allow 5 attempts before requiring new OTP
Setting this too high increases the risk of brute-force attacks. The default of 3 attempts provides good security while allowing for common typos.
​
messageTemplate
(otp: string, appName?: string) => string
A function that generates the SMS or email message containing the OTP code.Parameters:
  • otp (string): The generated OTP code
  • appName (string | undefined): Optional application name
Returns: The formatted message string
messageTemplate: (otp, appName) => {
  return `Your ${appName || "verification"} code is: ${otp}. Valid for 5 minutes.`
}
Default template:
(otp) => `Your verification code is: ${otp}`
Keep messages concise for SMS delivery. Most carriers support 160 characters for a single SMS segment.

​
Default Configuration

If no OTPConfig is provided, Arraf Auth uses these defaults: 
{
  length: 6,
  expiresIn: 300,        // 5 minutes
  maxAttempts: 3,
  messageTemplate: (otp) => `Your verification code is: ${otp}`
}

​
Usage Examples

​
Custom OTP Length and Expiration

import { createAuth } from "@arraf-auth/core"

const auth = createAuth({
  secret: process.env.AUTH_SECRET!,
  database: adapter,
  otp: {
    length: 4,           // Shorter code for easier typing
    expiresIn: 600,      // 10 minutes
    maxAttempts: 5,
  },
})

​
Branded Message Template

const auth = createAuth({
  secret: process.env.AUTH_SECRET!,
  database: adapter,
  otp: {
    length: 6,
    expiresIn: 300,
    messageTemplate: (otp, appName) => {
      return `Welcome to ${appName || "our app"}! Your verification code is ${otp}. This code expires in 5 minutes.`
    },
  },
})

​
High-Security Configuration

const auth = createAuth({
  secret: process.env.AUTH_SECRET!,
  database: adapter,
  otp: {
    length: 8,           // Longer code for higher security
    expiresIn: 180,      // 3 minutes
    maxAttempts: 2,      // Fewer attempts allowed
    messageTemplate: (otp) => {
      return `SECURITY CODE: ${otp}\nDo not share this code with anyone.`
    },
  },
})

​
Multi-Language Support

const auth = createAuth({
  secret: process.env.AUTH_SECRET!,
  database: adapter,
  otp: {
    messageTemplate: (otp, appName) => {
      const locale = process.env.LOCALE || "en"
      
      const messages = {
        en: `Your ${appName} code: ${otp}`,
        es: `Tu código de ${appName}: ${otp}`,
        fr: `Votre code ${appName}: ${otp}`,
      }
      
      return messages[locale] || messages.en
    },
  },
})

​
Security Considerations

Security best practices:
  • Use at least 6 digits for adequate security
  • Keep expiration times under 15 minutes
  • Limit attempts to prevent brute-force attacks
  • Always send OTPs over secure channels (HTTPS, encrypted SMS)
OTP codes are automatically deleted from the database after:
  • Successful verification
  • Expiration time is reached
  • Maximum attempts are exceeded

​
OTP Verification Flow

  1. User requests OTP via /auth/otp/send endpoint
  2. System generates random code based on length
  3. Message is formatted using messageTemplate
  4. Code is sent via configured SMS provider
  5. User submits code via /auth/otp/verify endpoint
  6. System validates code against:
    • Expiration time (expiresIn)
    • Attempt count (maxAttempts)
    • Code correctness
  7. On success, user is authenticated and session is created

Build docs developers (and LLMs) love

Get started for freeTalk to us