Skip to main content

​
Overview

The API uses JSON Web Tokens (JWT) for authentication. After successful login or registration, you’ll receive a token that must be included in subsequent requests to access protected endpoints.
Tokens expire after 30 days by default (configurable via JWT_EXPIRY_DAY).

​
Authentication Flow

1

Register or Login

Obtain a JWT token by registering a new account or logging in with existing credentials
2

Include Token in Requests

Add the token to the Authorization header of your requests
3

Refresh When Needed

Login again when your token expires to get a new one

​
Token-Based Authentication

​
JWT Token Structure

Tokens are issued in two formats: 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NSIsImlhdCI6MTYxNjIzOTAyMiwiZXhwIjoxNjE4ODMxMDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
The token payload contains:
  • sub: User ID
  • iat: Issued at timestamp
  • exp: Expiration timestamp
  • iev (optional): Exclusive membership flag

​
Using Your Token

Include the JWT token in the Authorization header: 
Authorization: Bearer YOUR_JWT_TOKEN
Example authenticated request:
curl
curl http://localhost:8001/api/v2/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Authentication Methods

The API supports multiple authentication methods:

Email & Password

Traditional login with email and password

Mobile OTP

SMS-based one-time password authentication

Google OAuth

Sign in with Google account

Facebook OAuth

Sign in with Facebook account

Apple OAuth

Sign in with Apple account

Two-Factor Auth

Enhanced security with OTP verification

​
Email & Password Login

Standard authentication using email and password credentials.

​
Request

POST /api/v2/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123"
}

​
Response

{
  "code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "user_id": 12345,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "is_exclusive": false
  }
}
The /api/v2/login endpoint includes reCAPTCHA validation for enhanced security.

​
Mobile OTP Authentication

Login using mobile number with OTP verification.
1

Request OTP

POST /api/v2/sendotp
Content-Type: application/json

{
  "phone_no": "+1234567890",
  "event": "login"
}
Response:
{
  "code": 200,
  "message": "OTP sent successfully",
  "event_id": "evt_abc123"
}
2

Verify OTP

POST /api/v2/verifyotp
Content-Type: application/json

{
  "phone_no": "+1234567890",
  "otp": "123456",
  "event_id": "evt_abc123"
}
3

Complete Login

POST /api/v2/login-mobile
Content-Type: application/json

{
  "phone_no": "+1234567890",
  "event_id": "evt_abc123"
}
Response includes JWT token:
{
  "code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Rate Limiting: OTP verification is limited to 3 attempts. After exceeding the limit, the user account is blocked for 24 hours.

​
Social Authentication

Login using social media accounts (Google, Facebook, Apple).

​
Google Login

POST /api/v2/googlelogin
Content-Type: application/json

{
  "access_token": "GOOGLE_ACCESS_TOKEN"
}

​
Facebook Login

POST /api/v2/facebooklogin
Content-Type: application/json

{
  "access_token": "FACEBOOK_ACCESS_TOKEN"
}

​
Apple Login

POST /api/v2/applelogin
Content-Type: application/json

{
  "id_token": "APPLE_ID_TOKEN",
  "authorization_code": "APPLE_AUTH_CODE"
}
All social login endpoints return a JWT token in the same format as email/password login.

​
Two-Factor Authentication

Enhanced security with OTP verification for sensitive operations.

​
Login with 2FA

1

Initial Login

POST /api/v2/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123"
}
If 2FA is enabled, you’ll receive:
{
  "code": 200,
  "message": "OTP sent to registered mobile",
  "requires_2fa": true,
  "event_id": "evt_2fa_abc123"
}
2

Verify 2FA OTP

POST /api/v2/login-tfa
Content-Type: application/json

{
  "email": "[email protected]",
  "otp": "123456",
  "event_id": "evt_2fa_abc123"
}
Success response:
{
  "code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Logout

Invalidate your token by logging out.

​
Single Device Logout

POST /api/v2/logout
Authorization: Bearer YOUR_TOKEN

​
All Devices Logout

Logout from all devices and invalidate all active tokens: 
POST /api/v2/logout-all-device
Authorization: Bearer YOUR_TOKEN
Logout adds your token to a blacklist stored in Redis with TTL matching the token expiration.

​
Error Responses

Common authentication errors: 
{
  "code": 10,
  "message": "Invalid credentials",
  "description": "Email or password is incorrect"
}

{
  "code": 21,
  "message": "User does not exist",
  "description": "No account found with this email"
}

{
  "code": 10,
  "message": "Unauthorized",
  "description": "Invalid or expired token"
}

{
  "code": 77,
  "message": "Account blocked",
  "description": "Your account has been blocked for 24 hours due to multiple failed OTP attempts"
}

{
  "code": 88,
  "message": "Too many requests",
  "description": "OTP verification limit exceeded"
}

​
Security Best Practices

Store Tokens Securely

Never store tokens in localStorage. Use httpOnly cookies or secure storage mechanisms.

Use HTTPS

Always transmit tokens over HTTPS to prevent interception.

Handle Expiration

Implement automatic token refresh or re-authentication when tokens expire.

Logout on Sensitive Actions

Implement logout functionality for user-initiated sign out.

​
Next Steps

User Registration

Learn how to register new users

Profile Management

Manage user profiles and settings

Error Handling

Understand error codes and handling

Rate Limits

Learn about API rate limiting

Build docs developers (and LLMs) love

Get started for freeTalk to us