Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Paramount-Intelligence/HR_Monitoring_System/llms.txt

Use this file to discover all available pages before exploring further.

The Workforce OS API uses a JWT-based authentication scheme. A successful login returns a short-lived access token and a longer-lived refresh token. The access token is passed as a Bearer credential on every protected request; the refresh token is used only to rotate the pair when the access token expires. All endpoints below are mounted at /api/v1/auth.
Token expiry defaults — Access tokens expire after 15 minutes and refresh tokens after 7 days. Both values are configurable via the ACCESS_TOKEN_EXPIRE_MINUTES and REFRESH_TOKEN_EXPIRE_DAYS environment variables respectively.

​
POST /auth/login

Authenticate with email and password. Returns a JWT access token, a refresh token, and basic user profile data. 
POST /api/v1/auth/login
Content-Type: application/json

​
Request Body

​
email
string
required
The user’s registered email address.
​
password
string
required
The user’s account password.

​
Example Request

curl -X POST https://<your-domain>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "s3cur3P@ssword"
  }'

​
Response

200 OK 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "018e4c2a-1234-7abc-9def-000000000001",
    "full_name": "Jane Doe",
    "role": "employee",
    "department": "Engineering",
    "designation": "Software Engineer",
    "avatar_url": null,
    "profile_picture_url": null,
    "presence_status": "active",
    "presence_updated_at": null,
    "last_seen_at": null,
    "online_state": "offline",
    "is_online": false
  }
}

​
Response Fields

​
access_token
string
Short-lived JWT (HS256). Include as Authorization: Bearer <access_token> on all protected requests. Expires after ACCESS_TOKEN_EXPIRE_MINUTES (default 15 minutes).
​
refresh_token
string
Longer-lived JWT used exclusively to rotate token pairs via POST /auth/refresh. Expires after REFRESH_TOKEN_EXPIRE_DAYS (default 7 days).
​
token_type
string
Always "bearer".
​
user
object
Authenticated user’s profile snapshot.
Accounts with status=suspended or status=inactive will receive a 401 AUTH_ERROR on every login attempt. Existing sessions for suspended users are invalidated on the next token refresh.

​
POST /auth/refresh

Exchange a valid refresh token for a new access token and a rotated refresh token. Call this endpoint when the access token has expired rather than prompting the user to log in again. 
POST /api/v1/auth/refresh
Content-Type: application/json

​
Request Body

​
refresh_token
string
required
The refresh token received from a previous login or refresh call.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Response

200 OK 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
​
access_token
string
Newly issued access token. Valid for ACCESS_TOKEN_EXPIRE_MINUTES minutes from issue time.
​
refresh_token
string
Rotated refresh token. The previous refresh token is invalidated immediately. Store this new value.
​
token_type
string
Always "bearer".
If the refresh token is invalid, expired, or has already been used, the API returns 401 AUTH_ERROR. The frontend should treat this as a session expiry and redirect the user to the login page.

​
POST /auth/logout

Invalidate the current session. The server revokes the provided refresh token in the database and the client should discard both tokens from local storage or cookies. 
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
Content-Type: application/json
A valid Authorization: Bearer <access_token> header is required. The endpoint identifies the acting user from the token, not from the body.

​
Request Body

​
refresh_token
string
Optional. The refresh token to explicitly revoke. If omitted, all refresh tokens for the authenticated user are invalidated.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Response

200 OK 
{ "message": "Logged out successfully" }

​
POST /auth/forgot-password

Request a password reset email. The API generates a single-use reset token and emails a reset link to the address provided. The response is intentionally vague to prevent user enumeration. 
POST /api/v1/auth/forgot-password
Content-Type: application/json

​
Request Body

​
email
string
required
The email address associated with the account that needs a password reset.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

​
Response

200 OK 
{
  "message": "If an account with this email exists, a reset link has been sent."
}
In development mode only, the response also includes a debug_token field containing the raw reset token for testing without a configured SMTP server. This field is never present in production.

​
POST /auth/reset-password

Complete a password reset using the token from the reset email. The token is invalidated immediately after use. 
POST /api/v1/auth/reset-password
Content-Type: application/json

​
Request Body

​
token
string
required
The password reset token extracted from the reset link sent to the user’s email.
​
new_password
string
required
The user’s new password. Minimum 8 characters.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6...",
    "new_password": "NewS3cur3P@ss"
  }'

​
Response

200 OK 
{ "message": "Password reset successful" }
If the token is invalid or expired the API returns 400 Bad Request: 
{
  "error": {
    "code": "API_ERROR",
    "message": "Invalid or expired reset token",
    "details": []
  }
}

​
POST /auth/activate-account

Activate an invited user account and set its initial password. When an Admin or HR user creates a new user, that user’s account is created with status=invited. The invitation email contains a unique token that must be submitted here together with the user’s chosen password. 
POST /api/v1/auth/activate-account
Content-Type: application/json
This endpoint is public — it does not require an Authorization header. The activation page on the frontend must not enforce an auth guard before the invited user has completed activation, as the user does not yet have an active session.

​
Request Body

​
token
string
required
The invitation token from the activation link sent to the user’s email.
​
password
string
required
The initial password the user wants to set. Minimum 8 characters.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/activate-account \
  -H "Content-Type: application/json" \
  -d '{
    "token": "invite-token-abc123...",
    "password": "InitialP@ss1"
  }'

​
Response

200 OK 
{ "message": "Account activated successfully. You can now log in." }
If the token is invalid or has already been used the API returns 400 Bad Request: 
{
  "error": {
    "code": "API_ERROR",
    "message": "Invalid or expired invitation token",
    "details": []
  }
}
After a successful activation the user’s status is set to active and they can authenticate via POST /auth/login.

​
POST /auth/ws-ticket

Issue a short-lived, single-use ticket that authorizes a WebSocket connection. The ticket is passed as a query parameter when opening the WebSocket so that a standard Authorization header cannot be used in the handshake. 
POST /api/v1/auth/ws-ticket
Authorization: Bearer <access_token>
A valid Authorization: Bearer <access_token> header is required. The ticket is scoped to the authenticated user and cannot be shared.

​
Example Request

cURL
curl -X POST https://<your-domain>/api/v1/auth/ws-ticket \
  -H "Authorization: Bearer <access_token>"

​
Response

200 OK 
{
  "ticket": "ws_ticket_a1b2c3d4e5f6...",
  "expires_in": 30
}
​
ticket
string
Short-lived opaque token. Pass as ?ticket=<ticket> when opening a WebSocket connection.
​
expires_in
integer
Seconds until the ticket expires. Tickets are valid for a very short window — open the WebSocket immediately after obtaining one.

​
GET /auth/me/permissions

Return the full set of resolved permissions for the currently authenticated user along with their role. 
GET /api/v1/auth/me/permissions
Authorization: Bearer <access_token>

​
Example Request

cURL
curl https://<your-domain>/api/v1/auth/me/permissions \
  -H "Authorization: Bearer <access_token>"

​
Response

200 OK 
{
  "user_id": "018e4c2a-1234-7abc-9def-000000000001",
  "role": "manager",
  "permissions": [
    "attendance:read",
    "leaves:approve",
    "projects:read",
    "tasks:write"
  ]
}
​
user_id
string
UUID of the authenticated user.
​
role
string
The user’s current role, e.g. employee, manager, hr, or admin.
​
permissions
array
Alphabetically sorted list of permission strings granted to this user’s role.

Build docs developers (and LLMs) love

Get started for freeTalk to us