User Management API Reference

This section provides a detailed reference for managing user accounts within the faizanGeek/ClaimProcessingSystem. It covers operations for user registration, authentication (login), and user profile management.

Authentication and Authorization

The system utilizes OAuth2 for authentication and JWT (JSON Web Tokens) for securing API endpoints.

Public Endpoints: The /register and /login endpoints are publicly accessible and do not require prior authentication.
Authenticated Endpoints: All other user management endpoints require an authenticated user. Upon successful login, a JWT token is issued. This token must be included in the Authorization header of subsequent requests as a Bearer token: Authorization: Bearer <your_jwt_token>.
Role-Based Access Control (RBAC): The system supports role-based access. Certain operations (e.g., deleting a user, updating another user's role) may require specific user roles (e.g., "ADMIN").

User Data Model (UserDTO)

Most successful responses for user-related operations will return a UserDTO object (or a list of UserDTOs), which contains the following fields:

Example UserDTO:

{
  "userId": 101,
  "username": "alice.wonder",
  "email": "alice.wonder@example.com",
  "role": "USER",
  "status": "active"
}

Endpoints

1. Register a New User

Endpoint: /register
Method: POST
Description: Creates a new user account. The provided password will be securely hashed upon registration.
Authentication: None (publicly accessible).

Request Body

Example Request Body:

{
  "username": "newuser",
  "passwordHash": "MySecretPassword123!",
  "email": "newuser@example.com",
  "role": "USER"
}

Response Body (Success: 200 OK)

A UserDTO object representing the newly registered user.

Example Response Body:

{
  "userId": 201,
  "username": "newuser",
  "email": "newuser@example.com",
  "role": "USER",
  "status": "active"
}

2. User Login

Endpoint: /login
Method: POST
Description: Authenticates a user with provided credentials and issues an OAuth2/JWT token for subsequent API access.
Authentication: None (publicly accessible).

Request Body

Example Request Body:

{
  "username": "alice.wonder",
  "password": "MySecretPassword123!"
}

Response Body (Success: 200 OK)

The successful login operation returns an OAuth2 token, typically including an access token (JWT), token type, expiration, and scope. This access token must be included in the Authorization header of all subsequent authenticated requests.

Example Response Body:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIFdvbmRlciIsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fWPfWw-...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write",
  "jti": "unique-jwt-identifier"
}

Error Responses

401 Unauthorized: If the provided credentials are invalid.

3. Retrieve User Profile by ID

Endpoint: /api/users/{userId}
Method: GET
Description: Retrieves the details of a specific user by their ID.
Authentication: Required (Bearer Token).
Authorization: Typically, the authenticated user must be requesting their own profile or have an administrative role.

Path Parameters

Example Request:

GET /api/users/101
Authorization: Bearer <your_jwt_token>

Response Body (Success: 200 OK)

A UserDTO object containing the user's details.

Example Response Body:

{
  "userId": 101,
  "username": "alice.wonder",
  "email": "alice.wonder@example.com",
  "role": "USER",
  "status": "active"
}

Error Responses

401 Unauthorized: If no valid token is provided.
403 Forbidden: If the authenticated user does not have permission to view the requested user's profile.
404 Not Found: If a user with the specified userId does not exist.

4. Update User Profile

Endpoint: /api/users/{userId}
Method: PUT
Description: Updates specific details of an existing user.
Authentication: Required (Bearer Token).
Authorization: The authenticated user must be updating their own profile or have an administrative role. Updating the role typically requires administrative privileges.

Path Parameters

Request Body

Include only the fields you wish to update. The username cannot be updated via this endpoint.

Example Request Body:

{
  "email": "alice.newemail@example.com",
  "status": "inactive"
}

Example Request:

PUT /api/users/101
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "email": "alice.newemail@example.com",
  "status": "inactive"
}

Response Body (Success: 200 OK)

A UserDTO object representing the updated user.

Example Response Body:

{
  "userId": 101,
  "username": "alice.wonder",
  "email": "alice.newemail@example.com",
  "role": "USER",
  "status": "inactive"
}

Error Responses

401 Unauthorized: If no valid token is provided.
403 Forbidden: If the authenticated user does not have permission to update the user or change the specified fields (e.g., role without admin rights).
404 Not Found: If a user with the specified userId does not exist.
400 Bad Request: If the request body contains invalid data or attempts to update non-updatable fields (e.g., username).

5. Delete a User

Endpoint: /api/users/{userId}
Method: DELETE
Description: Deletes a user account from the system. This action is typically irreversible.
Authentication: Required (Bearer Token).
Authorization: This operation almost always requires an administrative role.

Path Parameters

Example Request:

DELETE /api/users/201
Authorization: Bearer <your_admin_jwt_token>

Response Body (Success: 204 No Content)

No content is returned for a successful deletion.

Error Responses

401 Unauthorized: If no valid token is provided.
403 Forbidden: If the authenticated user does not have administrative privileges to delete a user.
404 Not Found: If a user with the specified userId does not exist.

6. Retrieve All Users

Endpoint: /api/users
Method: GET
Description: Retrieves a list of all registered users in the system.
Authentication: Required (Bearer Token).
Authorization: This operation typically requires an administrative role due to its broad access to user data.

Example Request:

GET /api/users
Authorization: Bearer <your_admin_jwt_token>

Response Body (Success: 200 OK)

A list of UserDTO objects.

Example Response Body:

[
  {
    "userId": 101,
    "username": "alice.wonder",
    "email": "alice.wonder@example.com",
    "role": "USER",
    "status": "active"
  },
  {
    "userId": 201,
    "username": "bob.builder",
    "email": "bob.builder@example.com",
    "role": "ADMIN",
    "status": "active"
  },
  {
    "userId": 301,
    "username": "charlie.chaplin",
    "email": "charlie.chaplin@example.com",
    "role": "USER",
    "status": "inactive"
  }
]

Error Responses

401 Unauthorized: If no valid token is provided.
403 Forbidden: If the authenticated user does not have administrative privileges to view all users.