Skip to main content

​
Endpoint

​
POST /auth/login
endpoint
Authenticate a user with email and password credentials

​
Authentication

This endpoint does not require authentication (public endpoint).

​
Request Body

​
username
string
required
User’s email address or username
​
password
string
required
User’s password

​
Response

​
success
boolean
required
Indicates whether the login was successful
​
message
string
required
Human-readable message describing the result
​
token
string
JWT access token for authenticated requests (only present on success)
​
user
object
User data object (only present on success)

​
Example Request

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

​
Example Response

​
Success Response (200 OK)

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe",
    "username": "johndoe",
    "avatarUrl": "https://example.com/avatars/1.png",
    "githubHandle": null,
    "githubId": null,
    "githubLinkedAt": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "themeConfig": {
      "theme": {
        "primaryColor": "#94cb04",
        "brightness": "light"
      }
    }
  }
}

​
Error Response (401 Unauthorized)

{
  "success": false,
  "message": "Invalid credentials"
}

​
Error Codes

Status CodeDescription
200Login successful
401Invalid username or password
422Validation error (missing fields)
429Too many login attempts
500Internal server error

​
Token Usage

The returned JWT token should be included in the Authorization header for all authenticated requests: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
The token is automatically stored in memory and persisted to secure storage. All subsequent API requests will include the token via the Dio interceptor (see api_service.dart:35).

​
Token Lifecycle

  • Tokens are cached in memory for performance (_cachedToken)
  • Tokens are persisted to SharedPreferences for session continuity
  • On 401 errors, the token is automatically cleared
  • The onUnauthorized callback is triggered to redirect to login
Store the token securely and never expose it in logs or client-side code. The token grants full access to the user’s account.

Build docs developers (and LLMs) love

Get started for freeTalk to us