On this page

12 endpoints.

MethodPathSummary
POST/api/auth/change-passwordChange user password
POST/api/auth/confirm-email-changeConfirm email change using verification token
POST/api/auth/forgot-passwordRequest password reset email
POST/api/auth/loginLogin to the platform
POST/api/auth/logoutLogout from the platform
GET/api/auth/meGet current user profile
PUT/api/auth/profileUpdate user profile
POST/api/auth/refreshRefresh JWT token
POST/api/auth/refresh-tokenRefresh tokens using a refresh token
POST/api/auth/request-email-changeRequest email change (sends verification to new email)
POST/api/auth/reset-passwordReset password using token from email
POST/api/auth/setup-passwordSetup password for new member after approval
POST /api/auth/change-password

Allows authenticated users to change their password. Requires current password verification and new password confirmation. Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
currentPasswordstring (password)yesCurrent password for verification
newPasswordstring (password)yesNew password (min 8 characters)
confirmPasswordstring (password)yesConfirmation of new password

Responses

StatusDescriptionBody
200Password changed successfullyobject
400Validation error (missing fields, passwords don't match, weak password, or new password same as current)Error
401Invalid current password or not authenticatedError
500Server errorError
POST /api/auth/confirm-email-change

Completes the email change process:

  1. Verifies the token from the verification link
  2. Updates user's email in database
  3. Sends success notification to new email
  4. Forces re-login for security

Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
tokenstringyesVerification token from email

Responses

StatusDescriptionBody
200Email changed successfully (requires re-login)object
400Invalid or expired token, email mismatch, or email already in useError
500Server errorError
POST /api/auth/forgot-password

Sends a password reset email if the email exists in the system. Always returns success to prevent email enumeration attacks. Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
emailstring (email)yesUser's email address

Responses

StatusDescriptionBody
200Password reset email sent (if email exists). Always returns success for security.object
400Invalid email formatError
429Too many requests (rate limited)Error
500Server errorError
POST /api/auth/login

Authenticates a user and returns a JWT token. Security checks:

  • Validates email and password
  • Checks account expiration (accountExpiresAt)
  • Checks account suspension (isActive)
  • Handles mustResetPassword flag for first-time login (admin-provisioned accounts)

Auth: Bearer JWT required.

Request body (required) — application/json

Type: LoginRequest

Responses

StatusDescriptionBody
200Login successful or password reset requiredobject
400Invalid request (missing fields or invalid email format)Error
401Invalid credentials or account not foundError
403Account suspended, expired, or user not authorized for tenantError
500Server errorError
POST /api/auth/logout

Logout endpoint (client-side token removal). Since JWT tokens are stateless, logout is primarily handled client-side by removing the token. Token blacklisting can be added in the future if needed.

Auth: Bearer JWT required.

Responses

StatusDescriptionBody
200Logged out successfullyobject
GET /api/auth/me

Returns the authenticated user's profile information along with their associated tenants/communities and roles. Auth: Bearer JWT required.

Responses

StatusDescriptionBody
200User profile retrievedobject
401Not authenticatedError
500Server errorError
PUT /api/auth/profile

Updates the authenticated user's profile information. Supports text fields and image uploads (avatar, coverImage). Auth: Bearer JWT required.

Request body (required) — multipart/form-data

FieldTypeRequiredDescription
firstNamestringnoUser's first name
middleNamestringnoUser's middle name
grandfatherNamestringnoUser's grandfather name
familyNamestringnoUser's family name
phonestringnoUser's phone number
emailstring (email)noUser's email address
descriptionstringnoUser's bio/description (max 200 characters)
employeeNumberstringnoEmployee number
birthDatestring (date)noDate of birth
genderenum: MALE, FEMALE, OTHERnoGender
maritalStatusenum: SINGLE, MARRIED, DIVORCED, WIDOWEDnoMarital status
nationalitystringnoNationality
cityCodestringnoCity code
regionstringnoRegion
citystringnoCity
bloodTypeenum: A+, A-, B+, B-, AB+, AB-, O+, O-noBlood type
specializationstringnoProfessional specialization
positionstringnoJob position
departmentstringnoDepartment
facebookstring (uri)noFacebook profile URL
twitterstring (uri)noTwitter profile URL
instagramstring (uri)noInstagram profile URL
linkedinstring (uri)noLinkedIn profile URL
youtubestring (uri)noYouTube channel URL
tiktokstring (uri)noTikTok profile URL
snapchatstringnoSnapchat username
whatsappstringnoWhatsApp number
telegramstringnoTelegram username
avatarstring (binary)noProfile avatar image (JPG, PNG, GIF, WEBP, max 5MB)
coverImagestring (binary)noProfile cover image (JPG, PNG, GIF, WEBP, max 5MB)

Responses

StatusDescriptionBody
200Profile updated successfullyobject
400Validation error (file too large, invalid file type, description too long)Error
401Not authenticatedError
500Server errorError
POST /api/auth/refresh

Generates a new JWT token with the same claims as the current token. Useful for extending session without re-authentication. Auth: Bearer JWT required.

Responses

StatusDescriptionBody
200Token refreshed successfullyobject
401Not authenticated or invalid tokenError
500Server errorError
POST /api/auth/refresh-token

Generates a new access + refresh token pair using a valid refresh token. Does NOT require authentication — the access token may be expired. This is the primary mechanism for mobile apps to renew sessions silently.

Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
refreshTokenstringyesThe refresh token received from login or previous refresh

Responses

StatusDescriptionBody
200Tokens refreshed successfullyobject
400Missing refresh token—
401Refresh token expired or invalid—
500Server error—
POST /api/auth/request-email-change

Initiates email change process:

  1. Requires password verification for security
  2. Validates new email format and availability
  3. Sends security alert to current email
  4. Sends verification link to new email

Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
newEmailstring (email)yesThe new email address
passwordstring (password)yesCurrent password for verification

Responses

StatusDescriptionBody
200Verification email sent to new addressobject
400Invalid email format, email already in use, or new email same as currentError
401Invalid password or not authenticatedError
429Too many requests (rate limited)Error
500Server errorError
POST /api/auth/reset-password

Resets the user's password using a valid reset token from the password reset email. Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
tokenstringyesReset token from password reset email
passwordstring (password)yesNew password (min 8 characters)
confirmPasswordstring (password)yesConfirmation of new password

Responses

StatusDescriptionBody
200Password reset successfullyobject
400Invalid token, expired token, or password validation failedError
500Server errorError
POST /api/auth/setup-password

Auth: Bearer JWT required.

Request body (required) — application/json

FieldTypeRequiredDescription
tokenstringno—
passwordstringno—

Responses

StatusDescriptionBody
200Password setup successful—