Skip to main content

Auth API

Base path: /api/auth

This section documents authentication and session endpoints. The API uses a JWT stored in an HTTP-only cookie named token. Clients should send this cookie on subsequent requests to authenticate.

Cookie details

  • Name: token
  • httpOnly: true
  • secure: true in production
  • sameSite: none in production, strict otherwise
  • maxAge: 1 year

Roles & Access​

Two principal user groups are supported:

  • Client — accessLevel: "client" (login permitted only if the client is active).
  • Staff — users with one of: super-admin, admin, sales, finance, agent.

Other staff access levels are rejected at login.

POST /api/auth/login​

Authenticate with email and password. On success, sets the token cookie and returns the user profile.

Request​

  • Body application/json
{
  "email": "user@example.com",
  "password": "••••••••"
}

Responses​

  • 200 OK — Login successful; cookie set.

    Body (client example)

    {
      "message": "Login successful",
      "user": {
        "id": 123,
        "name": "Client Name",
        "email": "client@example.com",
        "accessLevel": "client"
      }
    }

    Body (staff example)

    {
      "message": "Login successful",
      "user": {
        "id": 42,
        "name": "Admin User",
        "email": "admin@example.com",
        "accessLevel": "admin"
      }
    }

    The returned user object excludes sensitive/internal fields (e.g., passwordHash, isActive, timestamps).

  • 401 Unauthorized — Invalid credentials or disallowed access level; inactive clients are also rejected.

    { "message": "Invalid Credentials" }

  • 500 Internal Server Error

    { "message": "Error logging in" }

Notes

  • Clients must exist and be isActive = true to log in.
  • Staff logins are permitted only for access levels: super-admin, admin, sales, finance, agent.

DELETE /api/auth/logout​

Clears the auth cookie and ends the session.

Request​

  • No body.

Response​

  • 200 OK 
    { "message": "Logout successful" }

GET /api/auth/profile​

Returns the authenticated user’s profile. Requires a valid token cookie.

Request​

  • Send the token cookie set by the login endpoint.

Responses​

  • 200 OK

    {
      "message": "Logged in",
      "user": {
        "id": 123,
        "name": "Client Name",
        "email": "client@example.com",
        "accessLevel": "client"
      }
    }

    For clients, inactive accounts return 401. For staff, the profile also excludes sensitive/internal fields.

  • 401 Unauthorized — Missing/invalid token or inactive client.

    { "message": "Unauthorized" }

  • 500 Internal Server Error

    { "message": "Error retrieving user" }

POST /api/auth/requestPassword​

Initiates a password reset flow for an email address.

Request​

  • Body application/json
{ "email": "user@example.com" }

Response​

  • 200 OK — A generic success message (implementation may vary) 
    { "message": "If an account exists for this email, a reset link has been sent." }
  • 4xx/5xx — Error messages as applicable.

Implementation note: This endpoint triggers your reset process (e.g., emails a token). Exact messaging may differ per environment.

POST /api/auth/resetPassword​

Completes a password reset.

Request​

  • Body application/json

    The backend expects the payload required by your reset flow (typically a reset token and the new password). A common shape is:

    {
      "token": "reset-token-from-email",
      "password": "NewStrongPassword123"
    }

Response​

  • 200 OK — Password updated. Response body/message may vary by implementation.
  • 4xx/5xx — Error messages as applicable.

Usage Examples​

cURL — Login​

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret"}' \
  -i

Inspect Set-Cookie in the response headers; include that cookie in subsequent requests.

cURL — Get Profile (with cookie)​

curl https://your-domain.com/api/auth/profile \
  --cookie "token=YOUR_JWT_HERE"

cURL — Logout​

curl -X DELETE https://your-domain.com/api/auth/logout \
  --cookie "token=YOUR_JWT_HERE"

Error Model​

All endpoints return a JSON object with a message field on error. Additional fields may be included depending on the failure mode.

{ "message": "<description>", "error": { /* optional diagnostic info */ } }

Security Considerations​

  • The JWT is stored in an HTTP-only cookie to mitigate XSS token theft.
  • In production, cookies are secure and sameSite=none (required for cross-site usage over HTTPS).
  • Always use HTTPS in production.