Login User

Authenticates a user with either their email or username plus password, and returns a JWT valid for 7 days.

Endpoint

POST {{base_url}}/v1/auth/login

Headers

Header	Value
Content-Type	application/json

This endpoint does not require authentication — it's used to obtain a token.

---

Body Parameters

Parameter	Type	Required	Description
email_or_username	string	Yes	Your account's email address or username. If the value looks like an email (contains @ and a domain), it's matched against email; otherwise it's matched against username.
password	string	Yes	Your account password.

---

Example Request

JSON

{
  "email_or_username": "johndoe",
  "password": "Strong@123"
}

Bash

curl --location '{{base_url}}/v1/auth/login' \
--header 'Content-Type: application/json' \
--data '{
    "email_or_username": "johndoe",
    "password": "Strong@123"
}'

---

Example Response — 200 OK

JSON

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 42,
    "username": "johndoe",
    "email": "[email protected]",
    "mobile_no": "919876543210",
    "firstname": "John",
    "lastname": "Doe",
    "name": "John Doe",
    "user_type": "client",
    "role": "user",
    "api_base_url": null
  }
}

Response Fields

Field	Description
success	true on a successful login.
message	Human-readable confirmation.
token	JWT to use as Authorization: Bearer <token> on subsequent requests. Valid for 7 days.
user.id	Internal account ID (admin_id).
user.username	Account username.
user.email	Account email, or null if not set.
user.mobile_no	Account mobile number, or null if not set.
user.firstname / user.lastname	Account name fields.
user.name	Full name (firstname + lastname, trimmed).
user.user_type	Account type (e.g. client), or null.
user.role	Derived role — super, admin, or user (see Role Derivation below).
user.api_base_url	Account's configured API base URL, or null if not set.

---

Validation Rules

• Both email_or_username and password are required.
• The account looked up must be active (is_active = 0 — see Notes on this flag's meaning).
• If the account has an expiry date set, today's date must not be past it.
• The provided password must match the account's stored password hash.

---

Error Responses

Status	Message	Reason
400	Missing email_or_username or password	One or both fields not provided.
401	Invalid credentials	No account found for the given email/username, or password doesn't match.
401	Account is inactive	The matched account is not active.
401	Account expired. Please contact your administrator.	The account's expiry date has passed.

---

Notes

• Password hash compatibility: Password hashes are compared using bcrypt. Hashes stored with a $2y$ prefix (common from PHP/Laravel) are normalized to $2a$ before comparison, so accounts migrated from PHP-based systems continue to work.