Cross-Platform Client Authentication API (Android, iOS, Windows, macOS, Linux)

1. Universal Architecture Overview

The Pixahunt Client Authentication API is a single, unified REST API designed to power all client applications across every major operating system:

  • Mobile: Android, iOS
  • Desktop: Windows, macOS, Linux
  • Cross-Platform Frameworks: Flutter, React Native, Kotlin Multiplatform, Electron, Tauri, .NET MAUI

All authentication tokens are stateless Bearer tokens (valid for 90 days), hashed using SHA-256 on the server for maximum security.

Base URL: https://pixahunt.com/api/apps/v1/auth
Headers: Accept: application/json, Content-Type: application/json

2. Endpoints Reference

A. User Login

Endpoint: POST /api/apps/v1/auth/login

Authenticate an existing user with either their email or username and password. Supports client device intelligence.

Request Body:

{
  "login": "user@pixahunt.com",
  "password": "YourPassword123",
  "platform": "android",            // "android" | "ios" | "windows" | "macos" | "linux"
  "device_name": "Galaxy S24 Ultra",
  "device_brand": "Samsung",
  "device_model": "SM-S928B",
  "os_version": "Android 14",
  "app_version": "1.0.0",
  "device_id": "a938f322-6e21-4d37-8854-41d3b070477e"
}

Success Response (200 OK):

{
  "status": true,
  "message": "Login successful",
  "token_type": "Bearer",
  "access_token": "pxt_7a8b9c0d1e2f3g4h5i6j7k8l9m0n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6d7e8f",
  "expires_at": "2027-01-06T10:30:00+00:00",
  "device_info": {
    "platform": "android",
    "device_name": "Galaxy S24 Ultra",
    "country": "Bangladesh",
    "city": "Dhaka"
  },
  "user": {
    "id": 105,
    "username": "shajal",
    "fullname": "Shajal Ahmed",
    "email": "shajal@pixahunt.com",
    "avatar_url": "https://cdn.pixahunt.com/profile/xavt.jpg",
    "status": "ACTIVE"
  }
}

B. User Registration (Sign Up)

Endpoint: POST /api/apps/v1/auth/register

Request Body:

{
  "username": "pixa_user",
  "fullname": "John Doe",
  "email": "john@example.com",
  "password": "SecurePassword123",
  "password_confirmation": "SecurePassword123",
  "platform": "windows",
  "device_name": "ThinkPad X1 Carbon"
}

C. Universal Google Sign-In

Endpoint: POST /api/apps/v1/auth/google

Request Body:

{
  "id_token": "<GOOGLE_ID_TOKEN>",
  "platform": "ios",
  "device_name": "iPhone 15 Pro"
}

D. Forgot Password (Request 6-Digit Code & Link)

Endpoint: POST /api/apps/v1/auth/forgot-password

Generates a 6-digit numeric OTP (ideal for mobile/desktop apps) and sends a branded reset email containing both the verification code and clickable web link.

Request Body:

{
  "email": "user@example.com"
}

Success Response (200 OK):

{
  "status": true,
  "message": "A 6-digit verification code and reset link have been sent to your email.",
  "email": "user@example.com",
  "expires_in": "60 minutes"
}

E. Verify Reset Code (OTP Check)

Endpoint: POST /api/apps/v1/auth/verify-reset-code

Validates the code entered by the user in the client UI before advancing to the new password screen.

Request Body:

{
  "email": "user@example.com",
  "code": "849201"
}

Success Response (200 OK):

{
  "status": true,
  "message": "Verification code verified successfully. You may now set your new password."
}

F. Reset Password (Set New Password)

Endpoint: POST /api/apps/v1/auth/reset-password

Sets a new password using either the 6-digit code or link token.

Request Body:

{
  "email": "user@example.com",
  "code": "849201",
  "password": "NewSecurePassword123!",
  "password_confirmation": "NewSecurePassword123!"
}

Success Response (200 OK):

{
  "status": true,
  "message": "Password reset successfully! Please login with your new password."
}

G. Change Password (Authenticated)

Endpoint: POST /api/apps/v1/auth/change-password

Headers: Authorization: Bearer <access_token>

Request Body:

{
  "current_password": "CurrentPassword123!",
  "password": "NewPassword2026!",
  "password_confirmation": "NewPassword2026!"
}

H. Get Profile

Endpoint: GET /api/apps/v1/auth/me

Headers: Authorization: Bearer <access_token>

I. Logout & Logout All Devices

Endpoint: POST /api/apps/v1/auth/logout (Revokes current token)

Endpoint: POST /api/apps/v1/auth/logout-all (Revokes all active sessions)

Headers: Authorization: Bearer <access_token>

Next Step: User Profile Management & Bunny CDN Images

After authenticating the user via /api/apps/v1/auth/login or /api/apps/v1/auth/register, manage the user's editable profile information, social accounts, and Bunny CDN avatars & covers using the User Profile Management API:

  • GET /api/apps/v1/user/profile — Fetch user profile, editable field permissions, and CDN images
  • POST /api/apps/v1/user/profile — Update editable bio, location, website, privacy flags, and social links
  • POST /api/apps/v1/user/avatar — Upload and auto-optimize avatar to Bunny CDN (300x300 WebP)
  • POST /api/apps/v1/user/cover — Upload and auto-optimize banner to Bunny CDN (900x300 WebP)

See full documentation in the User Profile & Bunny CDN Media API Document.