API Endpoints

Below is a list of available API endpoints in the NovaStack project and their detailed descriptions.

Authentication

User Login

• URL: /api/auth/login
• Method: POST
• Description: Log in using username and password
• Request Body:

  {
    "username": "user@example.com",
    "password": "your_password",
    "deviceId": "unique-device-id"
  }

• Response Example:

  {
    "code": 0,
    "message": "Login successful",
    "user": {
      "id": 1,
      "username": "user",
      "email": "user@example.com"
    },
    "accessToken": "access-token-value",
    "refreshToken": "refresh-token-value",
    "expiresIn": 604800
  }

User Registration

• URL: /api/auth/register
• Method: POST
• Description: Create a new user account
• Request Body:

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

Refresh Token

• URL: /api/auth/refresh
• Method: POST
• Description: Use refresh token to obtain a new access token
• Response Example:

  {
    "code": 0,
    "message": "Refresh successful"
  }

User Logout

• URL: /api/auth/logout
• Method: POST
• Description: Log out user session and clear authentication cookies
• Request Body:

  {
    "deviceId": "unique-device-id"
  }

Get Captcha

• URL: /api/auth/captcha
• Method: POST
• Description: Get login captcha

User Management

Get Current User Info

• URL: /api/user/index
• Method: GET
• Description: Get information about the currently logged-in user
• Request Headers:
  • Cookie: auth-token=<token>
• Response Example:

  {
    "code": 0,
    "message": "User info retrieved successfully",
    "data": {
      "id": 1,
      "username": "user",
      "email": "user@example.com",
      "role": "admin"
    }
  }

Get User List

• URL: /api/user/list
• Method: GET
• Description: Get list of users (with pagination and search support)
• Request Headers:
  • Cookie: auth-token=<token>
• Query Parameters:
  • page: Page number (default: 1)
  • limit: Items per page (default: 10)
  • search: Search keyword
• Response Example:

  {
    "code": 0,
    "message": "User list retrieved successfully",
    "data": {
      "users": [...],
      "pagination": {
        "total": 100,
        "page": 1,
        "limit": 10,
        "totalPages": 10
      }
    }
  }

Get User Menus

• URL: /api/user/menus
• Method: GET
• Description: Get menu permissions for the current user
• Request Headers:
  • Cookie: auth-token=<token>

Delete User

• URL: /api/user/delete
• Method: POST
• Description: Delete a specific user
• Request Headers:
  • Cookie: auth-token=<token>
• Request Body:

  {
    "userId": 123
  }

Update User Role

• URL: /api/user/update-role
• Method: POST
• Description: Update user role
• Request Headers:
  • Cookie: auth-token=<token>
• Request Body:

  {
    "userId": 123,
    "roleId": 2
  }

Admin Features

Get All Users

• URL: /api/admin/users
• Method: GET
• Description: Admin gets list of all users
• Request Headers:
  • Cookie: auth-token=<token>

Create User

• URL: /api/admin/users
• Method: POST
• Description: Admin creates a new user
• Request Headers:
  • Cookie: auth-token=<token>
• Request Body:

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

Get Role List

• URL: /api/admin/roles
• Method: GET
• Description: Get list of all roles
• Request Headers:
  • Cookie: auth-token=<token>

Create Role

• URL: /api/admin/roles.create
• Method: POST
• Description: Create a new role
• Request Headers:
  • Cookie: auth-token=<token>
• Request Body:

  {
    "name": "editor",
    "description": "Editor role"
  }

Assign Role

• URL: /api/admin/assign-role
• Method: POST
• Description: Assign role to a user
• Request Headers:
  • Cookie: auth-token=<token>
• Request Body:

  {
    "userId": 123,
    "roleId": 2
  }

Get Menu List

• URL: /api/admin/menus
• Method: GET
• Description: Get system menu list
• Request Headers:
  • Cookie: auth-token=<token>

Unified Response Format

All API responses follow this format:

{
  "code": 0,
  "message": "success",
  "data": {}
}

• code: 0 - Success
• code !== 0 - Business error

Error Handling

Status Code	Description
200	Request completed successfully
400	Bad request, server cannot process
401	Authentication failed
403	Access forbidden
404	Requested resource does not exist
500	Internal server error

Authentication Notes

NovaStack uses a combination of Cookie and token authentication:

1. After successful login, the system sets the following cookies:

   • auth-token: Access token (30 minutes validity)
   • refresh-token: Refresh token (7 days validity)
   • isAuth: Authentication status indicator

2. Most API requests automatically read authentication from cookies

3. If the access token expires, the system will automatically use the refresh token to obtain a new access token

4. If the refresh token also becomes invalid, the user needs to log in again

Notes

1. All protected API endpoints require a valid authentication token
2. Sensitive information like user passwords should be transmitted via HTTPS
3. When a token expires, the system will automatically attempt to refresh it
4. Admin features require appropriate permissions to access
5. Pagination parameters start counting from 1