Skip to main content

Two-Factor Authentication (2FA)

Send OTP codes and verification messages for secure authentication.

Overview​

Use Transformify to send:

  • One-time passwords (OTP)
  • Login verification codes
  • Password reset codes
  • Transaction confirmations
  • Account verification

Implementation​

Step 1: Create an SMS OTP Template​

SMS is the standard channel for 2FA — universal, no app required:

curl -X POST https://api.transformify.mk/api/v1/templates/sms \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OTP Code",
    "templateContent": "Your verification code is: {{code}}. Valid for {{expiry}} minutes. Do not share this code with anyone."
  }'

Response (201 Created):

{
  "id": "generated-template-id",
  "name": "OTP Code",
  "channelType": "Smpp",
  "messageType": "SimpleText",
  "templateContent": "Your verification code is: {{code}}. Valid for {{expiry}} minutes. Do not share this code with anyone.",
  "createdAt": "2024-01-15T09:00:00Z"
}

Step 2: Create a Transactional SMS Campaign​

OTP messages need real-time delivery. Create a long-lived transactional campaign:

curl -X POST https://api.transformify.mk/api/v1/sms/campaigns \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OTP Messages",
    "templateId": "otp-template-id"
  }'

Response (201 Created):

{
  "campaignId": "generated-campaign-id",
  "name": "OTP Messages",
  "status": "InProgress",
  "createdAt": "2024-01-15T09:00:00Z"
}

Save the returned campaignId — you'll reuse it for all OTP messages.

Step 3: Send OTP on Demand​

When a user requests verification, send the OTP immediately:

curl -X POST https://api.transformify.mk/api/v1/sms/campaigns/{campaignId}/messages \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "38970123456",
    "externalUserId": "user_12345",
    "placeholders": {
      "code": "847293",
      "expiry": "5"
    }
  }'

Response (202 Accepted):

{
  "messageId": "generated-message-id",
  "campaignId": "campaign-id",
  "phoneNumber": "38970123456",
  "status": "Pending",
  "queuedAt": "2024-01-15T09:00:00Z"
}

Template Examples​

Login Verification​

{
  "templateContent": "Your login code is: {{code}}. Valid for 5 minutes."
}

Password Reset​

{
  "templateContent": "Password reset code: {{code}}. Use this code to reset your password. Expires in 15 minutes."
}

Transaction Confirmation​

{
  "templateContent": "Confirm your {{amount}} payment to {{merchant}}. Enter code: {{code}}. Did not make this request? Call us immediately."
}

Account Verification​

{
  "templateContent": "Welcome to {{appName}}! Verify your phone number with code: {{code}}"
}

Best Practices​

  1. Use SMS - SMS is the most reliable channel for 2FA, works without apps
  2. Keep codes short-lived - 5 minutes for login, 15 minutes for password reset
  3. Rate limit requests - Prevent abuse by limiting OTP requests per user
  4. Never log OTP codes - Treat them as sensitive data
  5. Include context - Tell users what the code is for and warn about sharing