Skip to main content

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:

HeaderTypeRequiredDescription
Content-TypestringYesMust 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:

ParameterTypeRequiredDescriptionValidation
phoneNumberstringYesUser's phone number in international formatMust match E.164 format: +[country][number] (1-14 digits after +)
passwordstringYesUser's passwordMin 8 chars, must contain uppercase, lowercase, digit, and special character (@$!%*?&#)
emailstringYesUser's email addressMust be valid email format
firstNamestringYesUser's first nameMax 30 characters, cannot be blank
lastNamestringYesUser's last nameMax 30 characters, cannot be blank
middleNamestringYesUser's middle nameMax 30 characters, cannot be blank
verificationChannelstringYesOTP delivery methodenum: 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:

FieldDescription
successBoolean indicating operation success (always true for successful requests)
httpStatusHTTP status code as string
messageHuman-readable success message
action_timeISO 8601 timestamp of when the response was generated
data.tempTokenJWT temporary token required for OTP verification (expires in 10 minutes)
data.messageSpecific message about OTP delivery channel
data.expireAtISO 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:

HeaderTypeRequiredDescription
Content-TypestringYesMust be "application/json"

Request JSON Sample:

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

Request Body Parameters:

ParameterTypeRequiredDescriptionValidation
tempTokenstringYesTemporary JWT token from registration responseMust be valid non-expired temp token
otpCodestringYes6-digit OTP code received via chosen channelMust 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:

FieldDescription
successBoolean indicating operation success
httpStatusHTTP status code as string
messageSuccess message confirming registration completion
action_timeISO 8601 timestamp of response generation
data.accessTokenJWT access token for API authentication (shorter lifespan)
data.refreshTokenJWT refresh token for obtaining new access tokens (longer lifespan)
data.userData.idUnique user identifier (UUID)
data.userData.userNameAuto-generated username (email prefix + random suffix)
data.userData.firstNameUser's first name
data.userData.lastNameUser's last name
data.userData.middleNameUser's middle name
data.userData.emailUser's email address
data.userData.isVerifiedOverall account verification status
data.userData.isEmailVerifiedEmail verification status
data.userData.isPhoneVerifiedPhone verification status
data.userData.rolesArray of user roles/permissions
data.userData.createdAtAccount creation timestamp
data.userData.editedAtLast 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
Back to top