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

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

Getting Started

Core Features

Additional Features

Authentication

Authentication API Documentation

Overview

Base URL

Authentication

Endpoints

Forgot Password

Change Password

Refresh Token

Setup Password

Error Responses

Notes

​Authentication API Documentation

​Overview

​Base URL

​Authentication

​Endpoints

​Login

​Forgot Password

​Change Password

​Refresh Token

​Setup Password

​Error Responses

​Notes

Authentication API Documentation

Overview

Base URL

Authentication

Endpoints

Login

Forgot Password

Change Password

Refresh Token

Setup Password

Error Responses

Notes