Authentication Service

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Short Description: The Authentication Service handles user registration, login, OTP verification, password reset, and token management for the NextGate social commerce platform. This service provides secure account management with multi-channel OTP verification and JWT-based authentication.

Hints:

• All OTP codes are 6-digit numbers with 10-minute expiration
• Rate limiting: Maximum 5 OTP requests per 10-minute window
• Resend cooldown: 2 minutes between resend attempts
• JWT tokens include access tokens (short-lived) and refresh tokens (long-lived)
• Phone numbers must be in international E.164 format (+1234567890)
• Passwords must meet strong security requirements (8+ chars, uppercase, lowercase, digit, special character)

---

Endpoints

1. Account Registration

Purpose: Register a new user account and initiate OTP verification process

Endpoint: POST https://apinexgate.glueauth.com/api/v1/auth/register

Access Level: 🌐 Public (No authentication required)

Authentication: None

Request Headers:

Header	Type	Required	Description
Content-Type	string	Yes	Must be "application/json"

Request JSON Sample:

{
  "phoneNumber": "+255712345678",
  "password": "SecurePass123!",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "Michael",
  "verificationChannel": "EMAIL"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
phoneNumber	string	Yes	User's phone number in international format	Must match E.164 format: +[country][number] (1-14 digits after +)
password	string	Yes	User's password	Min 8 chars, must contain uppercase, lowercase, digit, and special character (@$!%*?&#)
email	string	Yes	User's email address	Must be valid email format
firstName	string	Yes	User's first name	Max 30 characters, cannot be blank
lastName	string	Yes	User's last name	Max 30 characters, cannot be blank
middleName	string	Yes	User's middle name	Max 30 characters, cannot be blank
verificationChannel	string	Yes	OTP delivery method	enum: EMAIL, SMS, WHATSAPP, VOICE_CALL, PUSH_NOTIFICATION, EMAIL_AND_SMS, SMS_AND_WHATSAPP, ALL_CHANNELS

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Registration successful",
  "action_time": "2025-09-23T10:30:00",
  "data": {
    "tempToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "message": "OTP has been sent to your email",
    "expireAt": "2025-09-23T10:40:00"
  }
}

Response Fields:

Field	Description
success	Boolean indicating operation success (always true for successful requests)
httpStatus	HTTP status code as string
message	Human-readable success message
action_time	ISO 8601 timestamp of when the response was generated
data.tempToken	JWT temporary token required for OTP verification (expires in 10 minutes)
data.message	Specific message about OTP delivery channel
data.expireAt	ISO 8601 timestamp when the temp token expires

Error Responses:

• 400 Bad Request: Invalid request data, validation failures, or user already exists
• 422 Unprocessable Entity: Business logic validation errors (e.g., duplicate email/phone)
• 500 Internal Server Error: Server-side processing errors

Error Response Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User with provided credentials already exist, please login",
  "action_time": "2025-09-23T10:30:00",
  "data": "User with provided credentials already exist, please login"
}

---

2. Verify Registration OTP

Purpose: Complete user registration by verifying the OTP code sent during registration

Endpoint: POST https://apinexgate.glueauth.com/api/v1/auth/verify-otp

Access Level: 🌐 Public (Requires temporary token from registration)

Authentication: None (uses tempToken from registration response)

Request Headers:

Header	Type	Required	Description
Content-Type	string	Yes	Must be "application/json"

Request JSON Sample:

{
  "tempToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "otpCode": "123456"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
tempToken	string	Yes	Temporary JWT token from registration response	Must be valid non-expired temp token
otpCode	string	Yes	6-digit OTP code received via chosen channel	Must be exactly 6 digits (\d{6})

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Registration completed successfully. You are now logged in.",
  "action_time": "2025-09-23T10:35:00",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userData": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "johndoe-a1B2c3D",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "Michael",
      "email": "john.doe@example.com",
      "isVerified": true,
      "isEmailVerified": true,
      "isPhoneVerified": false,
      "roles": ["ROLE_NORMAL_USER"],
      "createdAt": "2025-09-23T10:30:00",
      "editedAt": "2025-09-23T10:35:00"
    }
  }
}

Response Fields:

Field	Description
success	Boolean indicating operation success
httpStatus	HTTP status code as string
message	Success message confirming registration completion
action_time	ISO 8601 timestamp of response generation
data.accessToken	JWT access token for API authentication (shorter lifespan)
data.refreshToken	JWT refresh token for obtaining new access tokens (longer lifespan)
data.userData.id	Unique user identifier (UUID)
data.userData.userName	Auto-generated username (email prefix + random suffix)
data.userData.firstName	User's first name
data.userData.lastName	User's last name
data.userData.middleName	User's middle name
data.userData.email	User's email address
data.userData.isVerified	Overall account verification status
data.userData.isEmailVerified	Email verification status
data.userData.isPhoneVerified	Phone verification status
data.userData.roles	Array of user roles/permissions
data.userData.createdAt	Account creation timestamp
data.userData.editedAt	Last modification timestamp

Error Responses:

• 400 Bad Request: Invalid OTP code format or missing required fields
• 401 Unauthorized: Invalid or expired temporary token
• 422 Unprocessable Entity: OTP verification failed, max attempts exceeded, or token already used
• 500 Internal Server Error: Server-side processing errors

---

Quick Reference Guide

Common HTTP Status Codes

• 200 OK: Successful GET/PUT/PATCH request
• 201 Created: Successful POST request
• 204 No Content: Successful DELETE request
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required/failed
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation errors
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Authentication Types

• Bearer Token: Include Authorization: Bearer your_access_token in headers
• Temporary Token: Used in request body for OTP verification flows
• Refresh Token: Used to obtain new access tokens when they expire
• None: No authentication required for public endpoints

Data Format Standards

• Dates: Use ISO 8601 format (2025-09-23T10:30:00Z)
• Phone Numbers: E.164 international format (+1234567890)
• UUIDs: Standard UUID format (123e4567-e89b-12d3-a456-426614174000)
• OTP Codes: 6-digit numeric strings
• Tokens: JWT format with proper expiration handling