Two-Factor Authentication (2FA) Tutorial

Learn how to implement secure two-factor authentication using SMS verification codes.

Step-by-Step Implementation

Initialize SMS Service

Before implementing 2FA, you need to authenticate with our API using your API key. Include it in the Authorization header.

curl -X POST "https://api.egkkikikikifistis.gr/v1/otp"
     -H "Authorization: Bearer YOUR_API_KEY"
     -H "Content-Type: application/json"
     -d '{"to":"+16175550123","otpLength":6}'

Send Verification Code

Our API will generate a 6-digit OTP and send it to the user's mobile number. The system will store the code for 30 minutes.

{
  "requestId": "REQ-789012",
  "status": "queued",
  "to": "+16175550123",
  "createdAt": "2025-10-04T14:20:00Z",
  "expiresAt": "2025-10-04T14:50:00Z"
}

⚠️ Note: Our SMS system uses carrier encryption for all 2FA transmissions

Verify User Code

Use the verification endpoint to confirm the user's submitted code. This validates both the code and timestamp.

curl -X POST "https://api.egkkikikifistis.gr/v1/otp/verify"
     -H "Authorization: Bearer YOUR_api_key"
     -H "Content-Type: application/json"
     -d '{"to":"+16175550123","code":"495021"}'

{
  "status": "valid",
  "matched": true,
  "remainingSeconds": 127,
  "firstLoginAt": "2025-10-04T14:20:13Z",
  "lastUsedAt": "2025-10-04T14:20:13Z"
}

Handle Session

When code is valid, create a secure session token. Our systems recommend JWT tokens with 24hr expiry for 2FA-verified users.


                            // Example token payload
{"sub": "user123", "iat": 45626555, "exp": 2155905247524, "session": "2fa_verified"}

ℹ️ Best Practice: Always combine OTP verification with IP whitelisting for added security

API Reference

POST /otp

to (string): Required MSISDN in E.164 format
otpLength (integer): Optional (default=6)

201 Created - Returns request tracking ID

POST /otp/verify

to (string): Required recipient number
code (string): Required verification code

200 OK - Returns verification status and timing information

403 Forbidden - Code expired, invalid or already used

Security Best Practices

Always Time-Lock Codes

All OTPs must have maximum 15 minute window with no extensions. System auto-cleans expired codes.

Rate Limiting

Limit resends to max 3 per hour per number to prevent attack vectors. Enable account lockout after 5 failed attempts.

Storage Encryption

Always store in-memory 30s rolling buffers using AES-256 at rest. Never store plaintext OTP codes.

Channel Diversity

Implement SMS fallback with email/Push notification system for edge scenarios.

What Developers Say

James Martin

"The 2FA implementation was seamless. We had multi-factor authentication live for our banking app in 2 hours."

Cathy Smith

"Clear documentation made it easier than any security implementation I've worked on. Our security audit passed first time."

Need Help with Implementation?

Our engineering team provides full integration support for enterprise customers.

Contact Support Team