Authentication

User authentication and registration

User login

post
/auth/login

Authenticate user and receive JWT tokens

Body
username_emailstringRequired

Username or email address

Example: johndoe
passwordstring · passwordRequired

User password

Example: Password123!
Responses
200

Login successful

application/json
post
/auth/login
POST /api/v3/auth/login HTTP/1.1
Host: localhost:8009
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "username_email": "johndoe",
  "password": "Password123!"
}
{
  "success": true,
  "code": 200,
  "message": "Login successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "[email protected]",
      "balance": 100.5,
      "referral_balance": 25,
      "referral_code": "CM12345678",
      "role": "user"
    }
  }
}

User registration

post
/auth/register

Register a new user account

Body
usernamestring · min: 3 · max: 50RequiredExample: johndoePattern: ^[a-zA-Z0-9_]+$
emailstring · emailRequiredExample: [email protected]
passwordstring · password · min: 8Required

Must contain uppercase, lowercase, number, and special character

Example: Password123!
referral_codestringOptional

Optional referral code

Example: CM12345678
device_fingerprintstringOptional

Device fingerprint for fraud detection

Example: abc123def456
Responses
post
/auth/register
POST /api/v3/auth/register HTTP/1.1
Host: localhost:8009
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "username": "johndoe",
  "email": "[email protected]",
  "password": "Password123!",
  "referral_code": "CM12345678",
  "device_fingerprint": "abc123def456"
}
{
  "success": true,
  "code": 201,
  "message": "Registration successful",
  "data": {
    "access_token": "text",
    "refresh_token": "text",
    "token_type": "text",
    "expires_in": 1,
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "[email protected]",
      "balance": 100.5,
      "referral_balance": 25,
      "referral_code": "CM12345678",
      "role": "user"
    }
  }
}

Refresh access token

post
/auth/refresh

Get a new access token using refresh token

Body
refresh_tokenstringRequiredExample: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Responses
200

Token refreshed successfully

application/json
post
/auth/refresh
POST /api/v3/auth/refresh HTTP/1.1
Host: localhost:8009
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
{
  "success": true,
  "code": 200,
  "message": "Token refreshed successfully",
  "data": {
    "access_token": "text",
    "refresh_token": "text",
    "token_type": "text",
    "expires_in": 1
  }
}

User logout

post
/auth/logout

Logout user (client should delete tokens)

Authorizations
AuthorizationstringRequired

JWT token obtained from login or register endpoint

Responses
200

Logout successful

application/json
post
/auth/logout
POST /api/v3/auth/logout HTTP/1.1
Host: localhost:8009
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Logout successful

{
  "success": true,
  "code": 200,
  "message": "Logout successful"
}

Request password reset

post
/auth/password-reset-request

Request a password reset link

Body
emailstring · emailRequiredExample: [email protected]
Responses
200

Reset link sent (if email exists)

application/json
post
/auth/password-reset-request
POST /api/v3/auth/password-reset-request HTTP/1.1
Host: localhost:8009
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "email": "[email protected]"
}
200

Reset link sent (if email exists)

{
  "success": true,
  "code": 200,
  "message": "If the email exists, a password reset link has been sent"
}
PreviousBase URLNextUser

Last updated