Auth API

The auth service handles user authentication via Better Auth and user profile management. Auth endpoints are proxied through the gateway at /auth/* and /user/*.

Better Auth Endpoints

These endpoints are handled by Better Auth and follow its API conventions:

Sign Up

POST /auth/sign-up/email

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "User Name"
}

Response: Sets better-auth.session_token cookie and returns user and session data.

Sign In

POST /auth/sign-in/email

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response: Sets session cookie, returns user and session data.

Sign Out

POST /auth/sign-out

Clears the session cookie and invalidates the server-side session.

Get Session

GET /auth/get-session

Returns the current session and user data. Used internally by the gateway for session verification.

Response:

{
  "session": {
    "id": "session-id",
    "userId": "user-id",
    "expiresAt": "2026-05-01T00:00:00Z"
  },
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user"
  }
}

User Profile Endpoints

Get Profile

GET /user/profile

Headers: Requires session cookie.

Response:

{
  "ok": true,
  "data": {
    "id": "user-id",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user",
    "created_at": "2026-04-01T00:00:00Z"
  }
}

Update Profile

PUT /user/profile

{
  "name": "New Name"
}

Error Codes

Code	Description
INVALID_CREDENTIALS	Wrong email or password
USER_EXISTS	Email already registered
USER_BANNED	Account has been banned by an admin
SESSION_EXPIRED	Session is no longer valid