API Reference
User

User Endpoints

Overview

This document provides details on the User Management endpoints, their functionality, expected use cases, and examples for integration with tools like cURL and Postman.

1. Create New User

Description

This endpoint is used to create a new user in the system.
It extracts the user ID from the request token, validates the request payload, and saves a new user to the database.

When to Use

  • When a new user account needs to be created in the system.
  • When the authenticated user submits their profile details for account creation.

Note: This endpoint is restricted to users with the owner or admin roles, as determined by the JWT token validation.

Endpoint Details

  • Method: POST
  • Path: /users
  • Headers:
    • Authorization: Bearer <token> (Required)

Request Payload

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com"
}

Response

  • Success (201 Created):
{
  "success": true,
  "message": "User created successfully"
}
  • Error Responses:
    • 401 Unauthorized: Token claims missing or invalid.
    • 400 Bad Request: Invalid request body.
    • 500 Internal Server Error: Failed to create user.

cURL Example

curl -X POST http://localhost:3010/api/users \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com"
}'

2. Get User Information

Description

This endpoint retrieves the details of the authenticated user.
It validates the user's token and fetches the user's information from the database using their ID.

When to Use

  • To fetch user profile information after authentication.
  • When displaying a user's account details in a dashboard.

Endpoint Details

  • Method: GET
  • Path: /users
  • Headers:
    • Authorization: Bearer <token> (Required)

Response

  • Success (200 OK):
{
  "id": "12345",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}
  • Error Responses:
    • 401 Unauthorized: Token claims missing or invalid.
    • 400 Bad Request: Invalid user ID.
    • 500 Internal Server Error: Failed to retrieve user.

cURL Example

curl -X GET http://localhost:3010/api/users \
-H "Authorization: Bearer <token>"

3. Update User Information

Description

This endpoint updates the details of the authenticated user.
It validates the user's token, parses the request payload, and updates the user record in the database.

When to Use

  • To update user profile information such as name or other personal details.
  • When the user edits their account settings.

Endpoint Details

  • Method: PUT
  • Path: /users
  • Headers:
    • Authorization: Bearer <token> (Required)

Request Payload

{
  "first_name": "John",
  "last_name": "Smith"
}

Response

  • Success (200 OK):
{
  "success": true,
  "message": "User updated successfully"
}
  • Error Responses:
    • 401 Unauthorized: Token claims missing or invalid.
    • 400 Bad Request: Invalid request body.
    • 500 Internal Server Error: Failed to update user.

cURL Example

curl -X PUT http://localhost:3010/api/users \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "first_name": "John",
  "last_name": "Smith"
}'
API IntroductionOrganizations