monorepo/cloud/maplepress-backend/docs/API/login.md

Login

POST /api/v1/login

Authenticate an existing user and obtain authentication tokens. This endpoint validates user credentials and creates a new session.

Authentication: None required (public endpoint)

Headers:

• Content-Type: application/json

Request Body:

Field	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password

Example Request:

curl -X POST http://localhost:8000/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "SecurePassword123!"
  }'

Example Response (200 OK):

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_email": "john@example.com",
  "user_name": "John Doe",
  "user_role": "user",
  "tenant_id": "650e8400-e29b-41d4-a716-446655440000",
  "session_id": "750e8400-e29b-41d4-a716-446655440000",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_expiry": "2024-10-24T12:15:00Z",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_expiry": "2024-10-31T00:00:00Z",
  "login_at": "2024-10-24T00:00:00Z"
}

Error Responses:

This endpoint returns errors in RFC 9457 (Problem Details for HTTP APIs) format.

Content-Type: application/problem+json

400 Bad Request - Invalid input:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request body format. Please check your JSON syntax."
}

401 Unauthorized - Invalid credentials:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid email or password."
}

429 Too Many Requests - Rate limit exceeded:

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many login attempts from this IP address. Please try again later."
}

500 Internal Server Error:

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Failed to process login. Please try again later."
}

Notes:

• The tenant_id is required for multi-tenant authentication to ensure user credentials are validated within the correct tenant context
• Access tokens expire after 15 minutes
• Refresh tokens expire after 7 days
• Both tokens are JWT tokens that should be stored securely on the client side
• Use the access token in the Authorization: JWT {token} header for authenticated requests