Skip to main content

​
Verification Interface

The Verification interface represents a verification code or OTP (One-Time Password) used for authenticating users, verifying email/phone, or resetting passwords.
​
id
string
required
Unique identifier for the verification record
​
identifier
string
required
The email address or phone number that this verification is for
​
token
string
required
The verification code or OTP token. This is what the user enters to verify their identity.
​
type
VerificationType
required
The type of verification. See Verification Types below.
​
expiresAt
Date
required
Timestamp when this verification expires. After this time, the code is no longer valid.
​
attempts
number
required
Number of times verification has been attempted. Used to prevent brute force attacks.
​
createdAt
Date
required
Timestamp when the verification was created

​
Verification Types

The VerificationType can be one of the following:
​
phone-otp
string
OTP sent via SMS for phone authentication
​
email-otp
string
OTP sent via email for email authentication
​
email-verification
string
Email verification link or code sent to confirm email ownership
​
password-reset
string
Password reset token sent to user’s email
​
phone-change
string
OTP sent when user is changing their phone number

​
Verification Flows

​
Phone OTP Flow

  1. User enters their phone number
  2. System creates a Verification record with type "phone-otp"
  3. OTP code is sent via SMS
  4. User enters the code
  5. System validates the code and creates/updates the user account

​
Email OTP Flow

  1. User enters their email address
  2. System creates a Verification record with type "email-otp"
  3. OTP code is sent via email
  4. User enters the code
  5. System validates the code and creates/updates the user account

​
Email Verification Flow

  1. User signs up with email and password
  2. System creates a Verification record with type "email-verification"
  3. Verification link/code is sent to the email
  4. User clicks link or enters code
  5. Email is marked as verified (emailVerified: true)

​
Password Reset Flow

  1. User requests password reset
  2. System creates a Verification record with type "password-reset"
  3. Reset link/code is sent to user’s email
  4. User clicks link or enters code
  5. User sets a new password

​
Usage Example

import { Verification, VerificationType } from "arraf-auth"

// Create phone OTP verification
const verification: Verification = await auth.createVerification({
  identifier: "+1234567890",
  token: "123456",
  type: "phone-otp",
  expiresAt: new Date(Date.now() + 10 * 60 * 1000), // 10 minutes
  attempts: 0
})

// Send OTP via SMS
await smsProvider.send({
  to: verification.identifier,
  message: `Your verification code is: ${verification.token}`
})

// Verify OTP
const existingVerification = await auth.getVerification(
  "+1234567890",
  "phone-otp"
)

if (existingVerification) {
  // Check expiration
  if (existingVerification.expiresAt < new Date()) {
    throw new Error("Verification code expired")
  }

  // Check attempts
  if (existingVerification.attempts >= 5) {
    throw new Error("Too many attempts")
  }

  // Verify token
  if (existingVerification.token === userInputCode) {
    // Success! Create or update user
    await auth.verifyPhone("+1234567890")
    await auth.deleteVerification(existingVerification.id)
  } else {
    // Increment attempts
    await auth.updateVerification(existingVerification.id, {
      attempts: existingVerification.attempts + 1
    })
    throw new Error("Invalid code")
  }
}
Verification codes should have a short expiration time (typically 5-15 minutes) and a maximum number of attempts (typically 3-5) to prevent abuse.
Configure OTP settings in AuthConfig.otp to customize code length, expiration time, max attempts, and SMS message template.

Build docs developers (and LLMs) love

Get started for freeTalk to us