Skip to main content
POST
/
api
/
auth
/
login
Login
curl --request POST \
  --url https://api.example.com/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>"
}
'
{
  "400": {},
  "401": {},
  "500": {},
  "success": true,
  "message": "<string>",
  "token": "<string>",
  "user": {
    "id": "<string>",
    "email": "<string>",
    "full_name": "<string>",
    "role": "<string>",
    "is_email_verified": true,
    "seller_profile": {
      "identity_document": "<string>",
      "selfie_url": "<string>",
      "verification_status": "<string>",
      "verification_method": "<string>",
      "verified_at": "<string>",
      "is_verified_badge": true
    }
  }
}

​
Endpoint

POST /api/auth/login

​
Authentication

No authentication required.

​
Request Body

​
email
string
required
User’s email address. Must be a valid email format.
​
password
string
required
User’s password.

​
Response

​
success
boolean
Indicates whether the login was successful.
​
message
string
Human-readable message describing the result.
​
token
string
JWT authentication token. Expires in 7 days by default.
​
user
object
User information including profile details.
​
id
string
User’s unique identifier.
​
email
string
User’s email address.
​
full_name
string
User’s full name.
​
role
string
User’s role (“seller” or “admin”).
​
is_email_verified
boolean
Whether the user’s email has been verified.
​
seller_profile
object
Seller-specific profile information. Null for admin users.
​
identity_document
string
URL or identifier for the seller’s identity document.
​
selfie_url
string
URL to the seller’s selfie image.
​
verification_status
string
Verification status: “pending”, “verified”, or “rejected”.
​
verification_method
string
Method used for verification: “manual” or “automatic”.
​
verified_at
string
ISO 8601 timestamp of when verification was completed.
​
is_verified_badge
boolean
Whether the seller has a verified badge displayed.

​
Example Request

curl -X POST https://api.horsetrust.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

​
Example Response

200 Success
{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "full_name": "John Smith",
    "role": "seller",
    "is_email_verified": false,
    "seller_profile": {
      "verification_status": "pending",
      "is_verified_badge": false
    }
  }
}

​
Error Responses

​
400
error
Bad Request - Validation error.
{
  "success": false,
  "message": "Valid email required"
}
​
401
error
Unauthorized - Invalid credentials or inactive account.
{
  "success": false,
  "message": "Invalid credentials"
}
​
500
error
Server Error - Internal server error.
{
  "success": false,
  "message": "Server error"
}

​
Notes

  • Email is normalized and converted to lowercase before authentication
  • Only active users (is_active: true) can log in
  • The last_login timestamp is automatically updated upon successful login
  • Password comparison is done securely using bcrypt
  • The JWT token contains the user’s ID and role, and should be included in the Authorization header for protected endpoints
  • Store the token securely (e.g., httpOnly cookies or secure storage) and never expose it in URLs or logs

Build docs developers (and LLMs) love

Get started for freeTalk to us