Android Authentication API

A secure, RESTful API for user authentication, SMS keyword management, and push notifications in Android applications

Documentation API Endpoints Keywords API

Key Features

Secure Authentication

Password hashing with bcrypt and JWT tokens for secure authorization

User Management

Complete user registration, login, and profile management

Notifications

Send global and user-specific notifications to your Android app

SMS Keywords

Centralized keyword management for SMS filtering with regex support

RESTful Design

Clean API design following REST principles for easy integration

API Documentation

This API provides authentication services for Android applications. Below you'll find information on how to integrate with the API.

Getting Started

Base URL

All API requests should be made to:

https://ideaforgeconnect.replit.app/api/auth/

Authentication

This API uses JWT (JSON Web Tokens) for authentication. After a successful login, you'll receive an access token and a refresh token. Include the access token in the Authorization header for protected endpoints.

Authorization: Bearer [your_access_token]

Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

{
  "message": "Success message",
  "data": {
    // Response data
  }
}

Error Handling

Errors are returned with appropriate status codes and a descriptive message.

{
  "error": "Error message",
  "details": "Detailed error information"
}

API Endpoints

User Registration

POST
Endpoint
/api/auth/register
Request Body
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "first_name": "John",     // Optional
  "last_name": "Doe"        // Optional
}
Success Response (201 Created)
{
  "message": "User registered successfully",
  "user_id": 1,
  "username": "johndoe"
}
Error Responses
  • 400 Bad Request - Missing required fields or invalid data
  • 409 Conflict - Username or email already exists
  • 500 Internal Server Error - Server error

User Login

POST
Endpoint
/api/auth/login
Request Body
{
  "username": "johndoe",
  "password": "SecurePass123!"
}
Success Response (200 OK)
{
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Error Responses
  • 400 Bad Request - Missing username or password
  • 401 Unauthorized - Invalid username or password
  • 403 Forbidden - Account is disabled
  • 500 Internal Server Error - Server error

Refresh Token

POST
Endpoint
/api/auth/refresh
Headers
Authorization: Bearer [refresh_token]
Success Response (200 OK)
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Error Responses
  • 401 Unauthorized - Invalid or expired refresh token
  • 500 Internal Server Error - Server error

Logout

POST
Endpoint
/api/auth/logout
Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "message": "Successfully logged out"
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

User Profile

GET
Endpoint
/api/auth/profile
Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "created_at": "2023-08-15T12:30:45"
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 404 Not Found - User not found
  • 500 Internal Server Error - Server error

Check Username Availability

GET
Endpoint
/api/auth/check_username/<username>
Success Response (200 OK)
{
  "exists": true // or false
}
Error Responses
  • 500 Internal Server Error - Server error

Check Email Availability

GET
Endpoint
/api/auth/check_email/<email>
Success Response (200 OK)
{
  "exists": true // or false
}
Error Responses
  • 500 Internal Server Error - Server error

Get User Progress

GET
Endpoint
/api/auth/me/progress
Description

Get the current user's level and progress percentage. This data syncs with your Android app for gamification features.

Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "success": true,
  "data": {
    "user_id": 1,
    "level": 3,
    "progress_to_next": 75,
    "updated_at": "2025-09-17T11:30:00.123456"
  }
}
Android Integration: Use this endpoint to sync user progress data with your Android app. The level represents the current user level, and progress_to_next shows percentage progress toward the next level.
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 404 Not Found - User not found
  • 500 Internal Server Error - Server error

Update User Progress Admin Only

PUT
Endpoint
/api/auth/admin/users/{user_id}/progress
Description

Update a specific user's level and progress percentage. Requires admin privileges.

Headers
Authorization: Bearer [admin_access_token]
Content-Type: application/json
URL Parameters
  • user_id: The ID of the user to update
Request Body
{
  "level": 5,
  "progress_to_next": 50
}
Field Validation
  • level - Integer, minimum value: 1
  • progress_to_next - Integer, range: 0-100 (percentage)
Success Response (200 OK)
{
  "success": true,
  "message": "User progress updated successfully",
  "data": {
    "user_id": 1,
    "level": 5,
    "progress_to_next": 50,
    "updated_at": "2025-09-17T11:30:00.123456"
  }
}
Admin Access Required: This endpoint requires the user to have admin privileges. Regular users will receive a 403 Forbidden response.
Error Responses
  • 400 Bad Request - Invalid input data or values out of range
  • 401 Unauthorized - Invalid or missing token
  • 403 Forbidden - User does not have admin privileges
  • 404 Not Found - Target user not found
  • 500 Internal Server Error - Server error

Notification Endpoints

These endpoints allow your Android application to retrieve and manage notifications.

List Notifications

GET
Endpoint
/api/notifications/list?page=1&per_page=10
Headers
Authorization: Bearer [access_token]
Query Parameters
  • page (optional): Page number for pagination (default: 1)
  • per_page (optional): Number of notifications per page (default: 10)
Success Response (200 OK)
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": 1,
        "title": "Welcome to the app!",
        "message": "Thank you for joining our platform.",
        "created_at": "2025-05-11T14:30:12.421Z",
        "is_global": true,
        "user_id": null,
        "is_read": false,
        "data": null
      },
      // More notifications...
    ],
    "total": 25,
    "pages": 3,
    "current_page": 1
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Get Unread Notification Count

GET
Endpoint
/api/notifications/unread/count
Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "success": true,
  "data": {
    "unread_count": 5
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Mark Notification as Read

POST
Endpoint
/api/notifications/read/{notification_id}
Headers
Authorization: Bearer [access_token]
URL Parameters
  • notification_id: The ID of the notification to mark as read
Success Response (200 OK)
{
  "success": true,
  "message": "Notification marked as read"
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 403 Forbidden - Trying to mark someone else's notification as read
  • 404 Not Found - Notification does not exist
  • 500 Internal Server Error - Server error

Notification API

Send and receive both global and user-specific notifications in your Android application.

Our Notification API allows you to:

  • Retrieve both global and user-specific notifications
  • Check for unread notifications
  • Mark notifications as read

Administrators can send notifications through the admin interface, which will then be delivered to your Android app.

View Notification API Documentation

Keyword Management API

These endpoints allow your Android application to sync keyword settings for SMS filtering and processing.

Sync Keywords

GET
Endpoint
/api/keywords/sync
Description

Get all keywords that should be available to the current user for sync. This includes global keywords and user-assigned keyword sets.

Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "success": true,
  "data": {
    "keywords": [
      {
        "id": 1,
        "keyword_set_id": 1,
        "name": "Banking Alerts",
        "word": "\\$\\d+(\\.\\d{2})?",
        "match_type": "regex",
        "case_sensitive": false,
        "is_active": true,
        "priority": 10,
        "service_type": "webhook",
        "webhook_url": "https://example.com/webhook",
        "created_at": "2025-09-17T05:00:00Z",
        "updated_at": "2025-09-17T05:00:00Z",
        "set_name": "Financial Keywords",
        "is_global": true
      },
      {
        "id": 2,
        "keyword_set_id": 2,
        "name": "Promotional Messages", 
        "word": "PROMO",
        "match_type": "contains",
        "case_sensitive": false,
        "is_active": true,
        "priority": 5,
        "service_type": null,
        "webhook_url": null,
        "created_at": "2025-09-17T05:00:00Z",
        "updated_at": "2025-09-17T05:00:00Z",
        "set_name": "Marketing Keywords",
        "is_global": false
      }
    ],
    "total_keywords": 2,
    "last_sync": "2025-09-17T05:00:00Z",
    "user_settings": {
      "auto_sync_enabled": true,
      "sync_interval_minutes": 15,
      "use_global_keywords": true,
      "custom_keywords_enabled": true,
      "match_priority_order": "priority"
    }
  }
}
Android Integration Tip: Use the name field for user-friendly display in your app, and the word field for actual SMS pattern matching.
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Get User Keyword Settings

GET
Endpoint
/api/keywords/settings
Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "success": true,
  "data": {
    "id": 1,
    "user_id": 1,
    "auto_sync_enabled": true,
    "sync_interval_minutes": 15,
    "last_sync": "2025-09-17T05:00:00Z",
    "use_global_keywords": true,
    "custom_keywords_enabled": true,
    "sms_processing_enabled": true,
    "match_priority_order": "priority",
    "created_at": "2025-09-17T04:30:00Z",
    "updated_at": "2025-09-17T05:00:00Z"
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Update User Keyword Settings

POST
Endpoint
/api/keywords/settings
Headers
Authorization: Bearer [access_token]
Request Body
{
  "auto_sync_enabled": true,
  "sync_interval_minutes": 30,
  "use_global_keywords": true,
  "custom_keywords_enabled": true,
  "sms_processing_enabled": true,
  "match_priority_order": "priority"
}
Field Descriptions
  • auto_sync_enabled - Enable/disable automatic keyword syncing
  • sync_interval_minutes - Sync interval (5-1440 minutes)
  • use_global_keywords - Include global/system keywords
  • custom_keywords_enabled - Include user-assigned keywords
  • sms_processing_enabled - Enable SMS processing with keywords
  • match_priority_order - Sort order: priority, alphabetical, chronological
Success Response (200 OK)
{
  "success": true,
  "message": "Settings updated successfully",
  "data": {
    // Updated user settings object
  }
}
Error Responses
  • 400 Bad Request - Invalid input data or values out of range
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Get Keyword Sets

GET
Endpoint
/api/keywords/sets
Headers
Authorization: Bearer [access_token]
Success Response (200 OK)
{
  "success": true,
  "data": {
    "keyword_sets": [
      {
        "id": 1,
        "name": "Financial Keywords",
        "description": "Keywords for banking and financial SMS messages",
        "is_global": true,
        "created_by": null,
        "created_at": "2025-09-17T04:00:00Z",
        "updated_at": "2025-09-17T04:30:00Z",
        "is_active": true,
        "keyword_count": 5,
        "user_has_access": true,
        "access_type": "global"
      },
      {
        "id": 2,
        "name": "Personal Keywords",
        "description": "User-specific keyword set",
        "is_global": false,
        "created_by": 1,
        "created_at": "2025-09-17T04:15:00Z",
        "updated_at": "2025-09-17T04:45:00Z",
        "is_active": true,
        "keyword_count": 3,
        "user_has_access": true,
        "access_type": "assigned"
      }
    ],
    "total_sets": 2
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 500 Internal Server Error - Server error

Get Keywords in Set

GET
Endpoint
/api/keywords/sets/{set_id}/keywords
Headers
Authorization: Bearer [access_token]
URL Parameters
  • set_id: The ID of the keyword set
Success Response (200 OK)
{
  "success": true,
  "data": {
    "keyword_set": {
      "id": 1,
      "name": "Financial Keywords",
      "description": "Keywords for banking and financial SMS messages",
      "is_global": true,
      "keyword_count": 3
    },
    "keywords": [
      {
        "id": 1,
        "keyword_set_id": 1,
        "name": "Banking Alerts",
        "word": "\\$\\d+(\\.\\d{2})?",
        "match_type": "regex",
        "case_sensitive": false,
        "is_active": true,
        "priority": 10,
        "service_type": "webhook",
        "webhook_url": "https://example.com/banking-webhook",
        "created_at": "2025-09-17T05:00:00Z",
        "updated_at": "2025-09-17T05:00:00Z"
      },
      {
        "id": 2,
        "keyword_set_id": 1,
        "name": "Account Balance",
        "word": "balance",
        "match_type": "contains",
        "case_sensitive": false,
        "is_active": true,
        "priority": 8,
        "service_type": null,
        "webhook_url": null,
        "created_at": "2025-09-17T05:00:00Z",
        "updated_at": "2025-09-17T05:00:00Z"
      }
    ],
    "total_keywords": 2
  }
}
Error Responses
  • 401 Unauthorized - Invalid or missing token
  • 403 Forbidden - Access denied to this keyword set
  • 404 Not Found - Keyword set does not exist
  • 500 Internal Server Error - Server error

Match Types Reference

Available Match Types
  • contains - Word appears anywhere in the message
  • exact - Message matches the word exactly
  • starts_with - Message begins with the word
  • ends_with - Message ends with the word
  • regex - Use regular expressions for complex patterns
Common Regex Patterns
PatternDescriptionExample
\\$\\d+(\\.\\d{2})?Dollar amounts$25, $1,234.56
[\\w\\.-]+@[\\w\\.-]+\\.\\w+Email addressesuser@example.com
\\d{3}-\\d{3}-\\d{4}Phone numbers123-456-7890
(?:urgent|alert|warning)Urgent keywordsurgent, alert, warning

Android Integration

Here's how to integrate this authentication API with your Android application:

Setting Up Retrofit

First, add Retrofit and GSON dependencies to your app's build.gradle file:

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.9.0'
}

Creating API Service Interface

Create an interface to define API endpoints:

public interface AuthApiService {
    @POST("api/auth/register")
    Call<RegisterResponse> registerUser(@Body RegisterRequest request);
    
    @POST("api/auth/login")
    Call<LoginResponse> loginUser(@Body LoginRequest request);
    
    @POST("api/auth/refresh")
    Call<RefreshResponse> refreshToken(@Header("Authorization") String refreshToken);
    
    @GET("api/auth/profile")
    Call<ProfileResponse> getUserProfile(@Header("Authorization") String token);
}

Setting Up Retrofit Client

Create a Retrofit client to handle API requests:

public class RetrofitClient {
    private static final String BASE_URL = "https://ideaforgeconnect.replit.app/";
    private static RetrofitClient instance;
    private final Retrofit retrofit;
    
    private RetrofitClient() {
        HttpLoggingInterceptor interceptor = new HttpLoggingInterceptor();
        interceptor.setLevel(HttpLoggingInterceptor.Level.BODY);
        
        OkHttpClient client = new OkHttpClient.Builder()
                .addInterceptor(interceptor)
                .build();
        
        retrofit = new Retrofit.Builder()
                .baseUrl(BASE_URL)
                .addConverterFactory(GsonConverterFactory.create())
                .client(client)
                .build();
    }
    
    public static synchronized RetrofitClient getInstance() {
        if (instance == null) {
            instance = new RetrofitClient();
        }
        return instance;
    }
    
    public AuthApiService getAuthService() {
        return retrofit.create(AuthApiService.class);
    }
}

Using the API in Your Android App

Example of how to call the login endpoint from your app:

LoginRequest loginRequest = new LoginRequest("username", "password");

RetrofitClient.getInstance()
    .getAuthService()
    .loginUser(loginRequest)
    .enqueue(new Callback<LoginResponse>() {
        @Override
        public void onResponse(Call<LoginResponse> call, Response<LoginResponse> response) {
            if (response.isSuccessful() && response.body() != null) {
                // Login successful
                LoginResponse loginResponse = response.body();
                
                // Save tokens for future requests
                saveTokens(loginResponse.getAccessToken(), loginResponse.getRefreshToken());
                
                // Navigate to main screen
                startActivity(new Intent(LoginActivity.this, MainActivity.class));
                finish();
            } else {
                // Handle error
                try {
                    JSONObject errorBody = new JSONObject(response.errorBody().string());
                    String errorMessage = errorBody.getString("error");
                    showError(errorMessage);
                } catch (Exception e) {
                    showError("Login failed");
                }
            }
        }
        
        @Override
        public void onFailure(Call<LoginResponse> call, Throwable t) {
            // Handle network error
            showError("Network error: " + t.getMessage());
        }
    });