User CRUD Operations

Production - UserController - POST, GET, PUT, DELETE /api/v1/users

User CRUD operations allow administrators to create, read, update, and delete user accounts within their tenant. Self-service endpoints allow authenticated users to view and update their own profile.

6.4.1Create User

curl -X POST http://localhost:8081/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "email": "new.user@company.com",
    "password": "InitialP@ss123",
    "firstName": "New",
    "lastName": "User",
    "displayName": "New User",
    "phoneNumber": "+1234567890",
    "roleIds": [1, 3]
  }'

Request Schema

Field	Type	Required	Validation	Description
`email`	String	Yes	`@NotBlank`, `@Email`, max 255	User email
`password`	String	Yes	`@NotBlank`, 8-128 chars	Initial password
`firstName`	String	No	Max 100	First name
`lastName`	String	No	Max 100	Last name
`displayName`	String	No	Max 200	Display name
`phoneNumber`	String	No	Max 20	Phone number
`roleIds`	Set<Long>	No		Role IDs to assign

Response (201 Created)

{
  "id": 42,
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "new.user@company.com",
  "firstName": "New",
  "lastName": "User",
  "displayName": "New User",
  "phoneNumber": "+1234567890",
  "enabled": true,
  "locked": false,
  "emailVerified": false,
  "mfaEnabled": false,
  "roles": [
    { "id": 1, "name": "user" },
    { "id": 3, "name": "analyst" }
  ],
  "createdAt": "2026-02-12T10:00:00Z",
  "updatedAt": "2026-02-12T10:00:00Z"
}

6.4.2Get User

# Get by ID (admin)
curl -X GET http://localhost:8081/api/v1/users/42 \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"
 
# Get current user (any authenticated user)
curl -X GET http://localhost:8081/api/v1/users/me \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

6.4.3List Users

Supports pagination and text search across name and email fields:

curl -X GET "http://localhost:8081/api/v1/users?search=jane&page=0&size=20" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Query Parameters

Parameter	Type	Default	Description
`search`	String	null	Search query for name or email
`page`	int	0	Page number (zero-based)
`size`	int	20	Page size
`sort`	String		Sort field and direction

6.4.4Update User

curl -X PUT http://localhost:8081/api/v1/users/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Updated",
    "lastName": "Name",
    "phoneNumber": "+0987654321"
  }'

6.4.5Delete User

Soft-deletes the user account. The record remains in the database with deleted=true.

curl -X DELETE http://localhost:8081/api/v1/users/42 \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Returns 204 No Content.

Error Codes

Code	HTTP Status	Description
`RESOURCE_NOT_FOUND`	404	User not found
`RESOURCE_DUPLICATE`	409	Email already exists in tenant
`VALIDATION_ERROR`	400	Invalid input
`ACCESS_DENIED`	403	Not ADMIN or PLATFORM_ADMIN

Overview Role Assignment