Skip to main content

​
Authentication API Documentation

​
Overview

The Authentication API provides endpoints for user authentication, password management, and token refresh functionality.

​
Base URL

/api/v1/auth

​
Authentication

Most endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key

​
Endpoints

​
Login

Authenticates a user and returns access and refresh tokens. Endpoint: POST /login Request Body: 
{
  "email": "string",
  "password": "string",
  "rememberMe": boolean
}
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "response": {
      "accessToken": "string",
      "user": {
        "userId": "string",
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "type": "string",
        "tenant": {
          "tenantId": "string",
          "name": "string"
        }
      }
    }
  }
}
Notes:
  • The refresh token is returned as an HTTP-only cookie
  • If rememberMe is true, the refresh token cookie will have a longer expiration time
  • The cookie is secure and SameSite=None to prevent CSRF attacks

​
Forgot Password

Initiates the password reset process by sending an OTP to the user’s email. Endpoint: GET /forgot-password/{email} Path Parameters:
  • email: User’s email address
Response: 
{
  "statusCode": 200,
  "message": "If this email is registered, a password reset OTP has been sent",
  "data": "string"
}

​
Change Password

Changes the user’s password using the OTP received from the forgot password process. Endpoint: POST /change-password Request Body: 
{
  "email": "string",
  "newPassword": "string",
  "otp": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "userId": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "type": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    }
  }
}

​
Refresh Token

Refreshes the access token using the refresh token from the cookie. Endpoint: GET /refresh-token Cookies:
  • refreshToken: The refresh token received during login
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "response": {
      "accessToken": "string",
      "user": {
        "userId": "string",
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "type": "string",
        "tenant": {
          "tenantId": "string",
          "name": "string"
        }
      }
    }
  }
}
Notes:
  • A new refresh token is returned as an HTTP-only cookie
  • The cookie is secure and SameSite=None to prevent CSRF attacks

​
Setup Password

Sets up the initial password for a user. Endpoint: POST /setup-password Headers:
  • X-API-KEY: API key for authentication
Request Body: 
{
  "password": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "password setup successfully",
  "data": "string"
}

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "User already has a password",
  "data": null
}

​
Notes

  • All passwords must meet the system’s security requirements
  • OTPs expire after 10 minutes
  • Refresh tokens are stored as HTTP-only cookies for security
  • Access tokens should be included in the Authorization header for protected endpoints
  • Tenant users cannot set up passwords