Users API
User account management endpoints.
Users API
The Users API provides endpoints for managing user accounts, roles, permissions, and user administration. Most endpoints require admin privileges.
Endpoints
GET /api/users
Retrieve users (Admin only).
Query Parameters:
role(string): Filter by user roleis_active(boolean): Filter by active statussearch(string): Search by name or emailpage(number): Page numberlimit(number): Items per page
Response:
{
"data": [
{
"id": "user_123",
"email": "john.doe@example.com",
"full_name": "John Doe",
"role": "manager",
"department": "Operations",
"is_active": true,
"last_login": "2024-01-15T15:30:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z"
},
{
"id": "user_456",
"email": "jane.smith@example.com",
"full_name": "Jane Smith",
"role": "employee",
"department": "Warehouse",
"is_active": true,
"last_login": "2024-01-15T14:20:00Z",
"created_at": "2024-01-05T00:00:00Z",
"updated_at": "2024-01-15T09:15:00Z"
}
],
"meta": {
"total": 25,
"page": 1,
"limit": 20,
"hasMore": true
}
}
GET /api/users/:id
Retrieve a specific user by ID.
Response:
{
"data": {
"id": "user_123",
"email": "john.doe@example.com",
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"role": "manager",
"department": "Operations",
"job_title": "Operations Manager",
"phone": "+1-555-0123",
"avatar_url": "https://example.com/avatars/user_123.jpg",
"timezone": "America/New_York",
"language": "en",
"preferences": {
"email_notifications": true,
"dashboard_layout": "compact",
"date_format": "MM/DD/YYYY"
},
"permissions": [
"inventory.read",
"inventory.write",
"orders.read",
"orders.write",
"reports.read"
],
"warehouse_access": [
{
"warehouse_id": "wh_789",
"warehouse_name": "Main Warehouse",
"access_level": "full"
}
],
"is_active": true,
"email_verified": true,
"last_login": "2024-01-15T15:30:00Z",
"login_count": 145,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
POST /api/users
Create a new user (Admin only).
Request Body:
{
"email": "new.user@example.com",
"full_name": "New User",
"first_name": "New",
"last_name": "User",
"role": "employee",
"department": "Warehouse",
"job_title": "Warehouse Associate",
"phone": "+1-555-0999",
"timezone": "America/Los_Angeles",
"language": "en",
"password": "temporary_password123",
"warehouse_access": [
{
"warehouse_id": "wh_789",
"access_level": "read_write"
}
],
"send_welcome_email": true
}
Response:
{
"data": {
"id": "user_789",
"email": "new.user@example.com",
"full_name": "New User",
"first_name": "New",
"last_name": "User",
"role": "employee",
"department": "Warehouse",
"job_title": "Warehouse Associate",
"phone": "+1-555-0999",
"timezone": "America/Los_Angeles",
"language": "en",
"permissions": [
"inventory.read",
"inventory.write",
"orders.read"
],
"warehouse_access": [
{
"warehouse_id": "wh_789",
"warehouse_name": "Main Warehouse",
"access_level": "read_write"
}
],
"is_active": true,
"email_verified": false,
"created_at": "2024-01-15T23:30:00Z",
"updated_at": "2024-01-15T23:30:00Z"
}
}
PUT /api/users/:id
Update user information (Admin only or own profile).
Request Body:
{
"full_name": "Updated Name",
"role": "manager",
"department": "Operations",
"job_title": "Senior Operations Manager",
"phone": "+1-555-0124",
"is_active": true,
"preferences": {
"email_notifications": false,
"dashboard_layout": "expanded",
"date_format": "DD/MM/YYYY"
}
}
Response:
{
"data": {
"id": "user_123",
"full_name": "Updated Name",
"role": "manager",
"department": "Operations",
"job_title": "Senior Operations Manager",
"phone": "+1-555-0124",
"preferences": {
"email_notifications": false,
"dashboard_layout": "expanded",
"date_format": "DD/MM/YYYY"
},
"updated_at": "2024-01-16T00:00:00Z"
}
}
DELETE /api/users/:id
Deactivate a user (Admin only).
Response:
{
"data": {
"message": "User successfully deactivated"
}
}
POST /api/users/:id/reset-password
Reset user password (Admin only).
Request Body:
{
"send_email": true,
"temporary_password": "temp_pass_123"
}
Response:
{
"data": {
"message": "Password reset successfully",
"temporary_password": "temp_pass_123",
"email_sent": true
}
}
PUT /api/users/:id/role
Update user role and permissions (Admin only).
Request Body:
{
"role": "admin",
"custom_permissions": [
"users.read",
"users.write",
"system.settings"
],
"warehouse_access": [
{
"warehouse_id": "wh_789",
"access_level": "full"
},
{
"warehouse_id": "wh_790",
"access_level": "read_only"
}
]
}
Response:
{
"data": {
"id": "user_123",
"role": "admin",
"permissions": [
"users.read",
"users.write",
"system.settings",
"inventory.read",
"inventory.write",
"orders.read",
"orders.write",
"reports.read",
"reports.write"
],
"warehouse_access": [
{
"warehouse_id": "wh_789",
"warehouse_name": "Main Warehouse",
"access_level": "full"
},
{
"warehouse_id": "wh_790",
"warehouse_name": "West Coast",
"access_level": "read_only"
}
],
"updated_at": "2024-01-16T00:30:00Z"
}
}
GET /api/users/:id/activity
Get user activity log (Admin only or own activity).
Query Parameters:
start_date(string): Start date for activity logend_date(string): End date for activity logaction_type(string): Filter by action typepage(number): Page numberlimit(number): Items per page
Response:
{
"data": [
{
"id": "activity_001",
"user_id": "user_123",
"action_type": "product_created",
"description": "Created product 'Smart Widget'",
"resource_type": "product",
"resource_id": "prod_123",
"ip_address": "192.168.1.100",
"user_agent": "Mozilla/5.0...",
"timestamp": "2024-01-15T15:30:00Z"
},
{
"id": "activity_002",
"user_id": "user_123",
"action_type": "login",
"description": "User logged in",
"ip_address": "192.168.1.100",
"timestamp": "2024-01-15T09:00:00Z"
}
],
"meta": {
"total": 150,
"page": 1,
"limit": 20,
"hasMore": true
}
}
GET /api/users/roles
Get available user roles and permissions.
Response:
{
"data": {
"roles": [
{
"name": "admin",
"display_name": "Administrator",
"description": "Full system access",
"permissions": [
"users.read",
"users.write",
"system.settings",
"inventory.read",
"inventory.write",
"orders.read",
"orders.write",
"reports.read",
"reports.write"
]
},
{
"name": "manager",
"display_name": "Manager",
"description": "Operational management access",
"permissions": [
"inventory.read",
"inventory.write",
"orders.read",
"orders.write",
"reports.read"
]
},
{
"name": "employee",
"display_name": "Employee",
"description": "Basic operational access",
"permissions": [
"inventory.read",
"inventory.write",
"orders.read"
]
},
{
"name": "viewer",
"display_name": "Viewer",
"description": "Read-only access",
"permissions": [
"inventory.read",
"orders.read",
"reports.read"
]
}
],
"permissions": [
{
"name": "users.read",
"description": "View user accounts"
},
{
"name": "users.write",
"description": "Create and modify user accounts"
},
{
"name": "inventory.read",
"description": "View inventory data"
},
{
"name": "inventory.write",
"description": "Modify inventory data"
}
]
}
}