Authentication

UnderstandingGET this/languages) flow│ is│ critical└── User picks language (e.g., "sw" for frontendSwahili) integration:

│
1. User└── signsApp instores vialanguage Firebase+ (Google,theme Apple,preference orlocally Email)│ on│ the│ mobile/web│ client
2.
2. USER SIGNS IN VIA FIREBASE │ │ └── Google Sign-In / Apple Sign-In / Email+Password │ │ └── Firebase returns an ID tokenToken │ │ │ │ 3. APP SENDS TO FURSA HUB BACKEND │ │ └── POST /auth/firebase/authenticate │ │ └── Include: firebaseToken, preferredLanguage, theme │ │ │ │ 4. BACKEND RESPONSE │ │ ├── NEW USER: Creates account, returns tokens + onboarding status │ │ └── EXISTING USER: Returns tokens + current onboarding status │ │ │ │ 5. CHECK ONBOARDING STATUS │ │ └── onboarding.isComplete = false → Navigate to theonboarding client
flow
3. Client│ sends│ Firebase└── IDonboarding.isComplete token= true → Navigate to POSThome /api/v1/auth/firebase/authenticate
screen
4. Backend│ verifies│ Firebase│ token,│ creates6. userTOKEN ifMANAGEMENT new│ │ └── Store accessToken (or retrieves existing), and returns custom JWT tokens
5. Client stores tokens securely - access token for API calls,calls) refresh│ token│ └── Store refreshToken (for renewal
renewing
6. CheckaccessToken) onboarding│ status│ in└── response to determine if user needs to complete onboarding steps

Token Refresh Flow

1. When access tokenaccessToken expires (you→ receive 401 UNAUTHORIZED), call POST /api/v1/auth/refresh │ │ │ └─────────────────────────────────────────────────────────────────────────┘
2. Backend validates refresh token and issues a new access token (same refresh token is returned)
3. Client updates stored access token and retries the failed request

Logout Flow

1. Client calls POST /api/v1/auth/logout with valid access token
2. Backend revokes all refresh tokens for the user
3. Client clears stored tokens locally

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-01-02T10:05T10:30:45",
  "data": {
    // Actual response data goes here }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-01-02T10:05T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Endpoints

1. Authenticate with Firebase

Purpose: Authenticate user withExchange Firebase ID token.token for Fursa Hub access tokens. Creates new user onif first login or returns existing user.time.

Endpoint: POST {base_url}/auth/firebase/authenticate

Access Level: 🌐 Public (No authentication required)

Authentication: None (Firebase token in body)

Request Headers:

Request JSON Sample:

{
  "firebaseToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "preferredLanguage": "en"sw",
  "theme": "DARK",
  "deviceInfo": "iPhoneAndroid 1414, Pro,Samsung iOSGalaxy 17.2"S24"
}

Request Body Parameters:

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Authentication successful",
  "action_time": "2025-01-02T10:05T10:30:45",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NTBl.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NTBl.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john.doe@gmail.user@example.com",
      "username": "johndoe",
      "phoneNumber": null,
      "fullName": "John Doe",
      "profilePhotoUrl": "https://lh3.googleusercontent.com/a/photo.jpg"...",
      "isPhoneVerified": false,
      "isEmailVerified": true,
      "preferredLanguage": "en"sw",
      "theme": "DARK",
      "authProvider": "GOOGLE",
      "role": "ROLE_USER",
      "createdAt": "2025-01-02T10:05T10:30:45"
    },
    "onboarding": {
      "isComplete": false,
      "currentStep": "PENDING_PHONE_VERIFICATION"
    }
  }
}

Success Response Fields:

Onboarding Status Values:

Error Response JSON Samples:

Invalid or Expired Firebase Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Invalid or expired Firebase token",
  "action_time": "2025-01-02T10:30:45",
  "data": "Invalid or expired Firebase token"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-01-02T10:30:45",
  "data": {
    "firebaseToken": "Firebase token is required"
  }
}

2. Refresh Access Token

Purpose: ObtainGet a new access token using a valid refresh token.token when current one expires.

Endpoint: POST {base_url}/auth/refresh

Access Level: 🌐 Public (No authentication required, but requires valid refresh token in body)

Authentication: None (refresh token is passed in request body)

Request Headers:

Request JSON Sample:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NTBl.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Request Body Parameters:

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Token refreshed successfully",
  "action_time": "2025-01-02T11:05T11:30:45",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NTBl.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI1NTBl.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": { "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john.doe@gmail.com",
      "username": "johndoe",
      "phoneNumber": "+255712345678",
      "fullName": "John Doe",
      "profilePhotoUrl": "https://lh3.googleusercontent.com/a/photo.jpg",
      "isPhoneVerified": true,
      "isEmailVerified": true,
      "preferredLanguage": "en",
      "authProvider": "GOOGLE",
      "role": "ROLE_USER",
      "createdAt": "2025-01-02T10:30:45"... },
    "onboarding": { "isComplete": true,
      "currentStep": "COMPLETED"... }
  }
}

Success Response Fields:

Error Response JSON SamplesResponses:

Invalid Refresh Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Invalid refresh token",
  "action_time": "2025-01-02T10:05T11:30:45",
  "data": "Invalid refresh token"
}

Expired Refresh Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Refresh token expired",
  "action_time": "2025-01-02T10:05T11:30:45",
  "data": "Refresh token expired"
}

Account Inactive or Locked (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Account is inactive or locked",
  "action_time": "2025-01-02T10:30:45",
  "data": "Account is inactive or locked"
}

3. Logout

Purpose: Logout user and revokeInvalidate all refresh tokens for the account.user, ending all sessions.

Endpoint: POST {base_url}/auth/logout

Access Level: 🔒 Protected (Requires valid access token)

Authentication: Bearer Token

Request Headers:

Request JSON Sample: No request body required

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Logged out successfully",
  "action_time": "2025-01-02T12:05T12:00:00",
  "data": null
}

Success Response Fields:

Error Response JSON Samples:

Missing or Invalid Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token is missing or invalid",
  "action_time": "2025-01-02T10:30:45",
  "data": "Token is missing or invalid"
}

Expired Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-01-02T10:30:45",
  "data": "Token has expired"
}

4. Get CurrentSupported UserLanguages

Purpose: RetrieveGet thelist currentlyof authenticatedsupported user'slanguages profilefor information.language selector screen.

Endpoint: GET {base_url}/auth/melanguages

Access Level: 🔒🌐 Protected (Requires valid access token)Public

Authentication: Bearer TokenNone

Request Headers:

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "UserLanguages retrieved successfully",
  "action_time": "2025-01-02T10:30:45"05T10:00:00",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@gmail.com",
    "username": "johndoe",
    "phoneNumber": "+255712345678",
    "fullName": "John Doe",
    "profilePhotoUrl": "https://lh3.googleusercontent.com/a/photo.jpg",
    "isPhoneVerified": true,
    "isEmailVerified": true,
    "preferredLanguage"code": "en",
      "authProvider"name": "GOOGLE"English",
      "role"nativeName": "ROLE_USER"English"
    },
    {
      "code": "sw",
      "createdAt"name": "2025-01-02T10:30:45"Swahili",
      "nativeName": "Kiswahili"
    },
    {
      "code": "fr",
      "name": "French",
      "nativeName": "Français"
    },
    {
      "code": "zh",
      "name": "Chinese",
      "nativeName": "中文"
    }
  ]
}

Success Response Fields:

Error Response JSON Samples:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token is missing or invalid",
  "action_time": "2025-01-02T10:30:45",
  "data": "Token is missing or invalid"
}

Standard Error Types

Application-Level Exceptions (400-499)

Server-Level Exceptions (500+)

Frontend Implementation Guide

TokenStep Storage1: Recommendations

App
• Mobile (iOS/Android): Use secure storage (Keychain for iOS, EncryptedSharedPreferences for Android)
• Web: Use httpOnly cookies or secure localStorage with proper XSS protection
• Never store tokens in plain text or expose them in URLs

Handling Token ExpirationLaunch

1.Show Makelanguage APIselector requestscreen
with access token
2. If 401 UNAUTHORIZED received:
   a.├── Call GET /auth/refresh with refresh token
   b. If refresh successful: Update stored access token, retry original request
   c. If refresh fails (401): Clear all tokens, redirectlanguages to loginget 3.options
Continue├── withUser responseselects language
├── Store locally: selectedLanguage, theme (default: SYSTEM)
└── Navigate to sign-in screen

HandlingStep Onboarding2: StatusSign In

After

Firebase successfulSign-In
authentication,├── checkUse Firebase SDK (Google/Apple/Email)
├── On success, get Firebase ID token
└── Call POST /auth/firebase/authenticate with:
    - firebaseToken
    - preferredLanguage (from step 1)
    - theme (from step 1)
    - deviceInfo (optional)

Step 3: Handle Response

Check response.data.onboarding.currentStep:
isComplete
├── 
PENDING_PHONE_VERIFICATIONfalse → Navigate to phoneonboarding verificationflow
screen
│   
PENDING_PREFERENCES└── Start at response.data.onboarding.currentStep
└── true → Navigate to preference selection screens

PENDING_PROFILE_COMPLETION → Navigate to profile completionhome screen

COMPLETED → Navigate to main app/dashboard



Quick Reference

Authentication Header Format

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

SupportedStep Languages4: Store Tokens
Save 
securely:
├── accessToken → For Authorization header
├── refreshToken → For token renewal











Code
Language
en
English
sw
Swahili
fr
French
zh
Chinese

User Roles











data→For










Role
Description
ROLE_USER
Standard└── user (default)
 
 
 
UI display

Step 5: API Calls

ROLE_MODERATORAll protected endpoints:
├── Add header: Authorization: Bearer {accessToken}
├── On 401 error → Try refresh token
│   ├── Success → Retry original request
│   └── Fail → Force re-login
└── Continue normal flow

Content moderator
ROLE_ADMIN
Administrator
ROLE_SUPER_ADMIN
Super administrator with full access