All user management endpoints require admin role authentication.
List Users
Retrieve a paginated list of all users in the system.
Query Parameters
Number of users to skip for pagination
Maximum number of users to return
Response
Operation status (success or error)
Array of user objects with their details
Whether the user is active
Timestamp of user creation
curl -X GET "https://api.example.com/api/v1/users/?skip=0&limit=10" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
{
"status": "success",
"count": 2,
"users": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"email": "[email protected]",
"role_id": 1,
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
},
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"username": "warehouse_manager",
"email": "[email protected]",
"role_id": 2,
"is_active": true,
"created_at": "2024-01-16T14:20:00Z"
}
]
}
Get User by ID
Retrieve detailed information about a specific user.
Path Parameters
Unique identifier of the user
Response
Operation status (success or error)
curl -X GET "https://api.example.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
{
"status": "success",
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"email": "[email protected]",
"role_id": 1,
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
}
Create User
Create a new user account. Automatically sends a welcome email to the new user.
Request Body
Unique username for the new user
Email address for the new user
Password for the new user account
Role ID to assign to the user (1=admin, 2=manager, 3=operator)
Response
Operation status (success or error)
curl -X POST "https://api.example.com/api/v1/users/" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "new_operator",
"email": "[email protected]",
"password": "SecurePass123!",
"role_id": 3
}'
{
"status": "success",
"message": "Usuario 'new_operator' creado exitosamente.",
"user": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"username": "new_operator",
"email": "[email protected]",
"role_id": 3,
"is_active": true,
"created_at": "2024-03-04T09:15:00Z"
}
}
Update User
Update an existing user’s information.
Path Parameters
Unique identifier of the user to update
Request Body
New email address (optional)
Response
Operation status (success or error)
curl -X PUT "https://api.example.com/api/v1/users/770e8400-e29b-41d4-a716-446655440002" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"role_id": 2
}'
{
"status": "success",
"message": "Usuario actualizado correctamente.",
"user": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"username": "new_operator",
"email": "[email protected]",
"role_id": 2,
"is_active": true,
"created_at": "2024-03-04T09:15:00Z"
}
}
Deactivate User
Deactivate a user account. This prevents the user from logging in but preserves their data.
Path Parameters
Unique identifier of the user to deactivate
Response
Operation status (success or error)
Confirmation message with username
Updated user object with is_active set to false
curl -X PATCH "https://api.example.com/api/v1/users/770e8400-e29b-41d4-a716-446655440002/deactivate" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
{
"status": "success",
"message": "Usuario 'new_operator' desactivado.",
"user": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"username": "new_operator",
"email": "[email protected]",
"role_id": 2,
"is_active": false,
"created_at": "2024-03-04T09:15:00Z"
}
}
List Roles
Retrieve all available user roles in the system.
Response
Operation status (success or error)
Array of role objects
Role name (e.g., admin, manager, operator)
curl -X GET "https://api.example.com/api/v1/users/roles" \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN"
{
"status": "success",
"roles": [
{
"id": 1,
"name": "admin",
"description": "Full system access"
},
{
"id": 2,
"name": "manager",
"description": "Warehouse management access"
},
{
"id": 3,
"name": "operator",
"description": "Basic inventory operations"
}
]
}