Users API

Complete user management endpoints for the SUDIGITAL platform.

Overview

The Users API provides comprehensive user management functionality including creation, authentication, profile management, and administrative operations. All endpoints follow RESTful conventions and return JSON responses.

Base URL

http://localhost:3001/api/users

Authentication

Most user endpoints require authentication. Include your JWT token in the Authorization header:

http

Authorization: Bearer your-jwt-token

Endpoints

Get All Users

Retrieve a paginated list of all users in the system.

http

GET /api/users

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number for pagination
`limit`	integer	20	Number of users per page (max 100)
`search`	string	-	Search users by name or email
`role`	string	-	Filter by user role (admin, user, viewer)
`status`	string	-	Filter by status (active, inactive, pending)
`sort`	string	created_at	Sort field (created_at, email, firstName, lastName)
`order`	string	desc	Sort order (asc, desc)

Response

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "status": "active",
      "avatar": "https://example.com/avatar.jpg",
      "emailVerified": true,
      "lastLoginAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

Example Request

bash

curl -X GET "http://localhost:3001/api/users?page=1&limit=10&search=john&role=user" \
  -H "Authorization: Bearer your-jwt-token"

Create User

Create a new user account.

http

POST /api/users

Request Body

json

{
  "email": "jane.smith@example.com",
  "password": "SecurePassword123!",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "user"
}

Required Fields

Field	Type	Description
`email`	string	Valid email address (unique)
`password`	string	Password (min 8 chars, complexity requirements)
`firstName`	string	User's first name
`lastName`	string	User's last name

Optional Fields

Field	Type	Default	Description
`role`	string	user	User role (admin, user, viewer)
`status`	string	pending	Account status
`avatar`	string	-	Profile picture URL

Response

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "user",
    "status": "pending",
    "avatar": null,
    "emailVerified": false,
    "lastLoginAt": null,
    "createdAt": "2024-01-16T10:30:00.000Z",
    "updatedAt": "2024-01-16T10:30:00.000Z"
  }
}

Get User by ID

Retrieve a specific user by their ID.

http

GET /api/users/{id}

Path Parameters

Parameter	Type	Description
`id`	UUID	User's unique identifier

Response

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "status": "active",
    "avatar": "https://example.com/avatar.jpg",
    "emailVerified": true,
    "lastLoginAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "profile": {
      "bio": "Software developer passionate about TypeScript",
      "location": "San Francisco, CA",
      "website": "https://johndoe.dev",
      "twitter": "@johndoe"
    }
  }
}

Update User

Update an existing user's information.

http

PUT /api/users/{id}

Request Body

json

{
  "firstName": "John Updated",
  "lastName": "Doe Updated",
  "role": "admin",
  "status": "active",
  "profile": {
    "bio": "Updated bio",
    "location": "New York, NY"
  }
}

Updatable Fields

Field	Type	Description
`firstName`	string	User's first name
`lastName`	string	User's last name
`role`	string	User role (admin users only)
`status`	string	Account status (admin users only)
`avatar`	string	Profile picture URL
`profile`	object	Additional profile information

Response

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "firstName": "John Updated",
    "lastName": "Doe Updated",
    "role": "admin",
    "status": "active",
    "avatar": "https://example.com/avatar.jpg",
    "emailVerified": true,
    "lastLoginAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-16T11:00:00.000Z"
  }
}

Delete User

Delete a user account (soft delete).

http

DELETE /api/users/{id}

Response

json

{
  "message": "User deleted successfully",
  "deletedAt": "2024-01-16T11:30:00.000Z"
}

Get Current User

Get the currently authenticated user's information.

http

GET /api/users/me

Response

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "status": "active",
    "avatar": "https://example.com/avatar.jpg",
    "emailVerified": true,
    "lastLoginAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "permissions": ["users:read", "users:update"],
    "preferences": {
      "theme": "dark",
      "language": "en",
      "notifications": {
        "email": true,
        "push": false
      }
    }
  }
}

Update Current User

Update the currently authenticated user's profile.

http

PUT /api/users/me

Request Body

json

{
  "firstName": "John",
  "lastName": "Doe",
  "avatar": "https://example.com/new-avatar.jpg",
  "profile": {
    "bio": "Updated bio",
    "website": "https://newwebsite.com"
  },
  "preferences": {
    "theme": "light",
    "notifications": {
      "email": false
    }
  }
}

Change User Password

Change the current user's password.

http

PUT /api/users/me/password

Request Body

json

{
  "currentPassword": "CurrentPassword123!",
  "newPassword": "NewSecurePassword123!"
}

Response

json

{
  "message": "Password updated successfully"
}

Upload User Avatar

Upload a profile picture for the current user.

http

POST /api/users/me/avatar
Content-Type: multipart/form-data

Request Body

avatar: [file] (image/jpeg, image/png, max 5MB)

Response

json

{
  "data": {
    "avatar": "https://cdn.sudigital.com/avatars/550e8400-e29b-41d4-a716-446655440000.jpg",
    "thumbnails": {
      "small": "https://cdn.sudigital.com/avatars/550e8400-e29b-41d4-a716-446655440000_small.jpg",
      "medium": "https://cdn.sudigital.com/avatars/550e8400-e29b-41d4-a716-446655440000_medium.jpg"
    }
  }
}

Get User Activity

Get activity log for a specific user.

http

GET /api/users/{id}/activity

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page
`type`	string	-	Activity type filter
`from`	datetime	-	Start date filter
`to`	datetime	-	End date filter

Response

json

{
  "data": [
    {
      "id": "activity-uuid",
      "type": "login",
      "description": "User logged in",
      "metadata": {
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0..."
      },
      "createdAt": "2024-01-16T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 250
  }
}

User Roles & Permissions

Available Roles

Role	Description	Permissions
`admin`	System administrator	Full access to all resources
`user`	Regular user	Standard user operations
`viewer`	Read-only access	View-only permissions

Permission Matrix

Action	Admin	User	Viewer
List all users	✅	❌	❌
View user details	✅	Own only	Own only
Create users	✅	❌	❌
Update users	✅	Own only	❌
Delete users	✅	❌	❌
Change user roles	✅	❌	❌

Error Responses

Validation Errors

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters"
      }
    ]
  },
  "status": 400
}

Common Error Codes

Code	Status	Description
`USER_NOT_FOUND`	404	User does not exist
`EMAIL_ALREADY_EXISTS`	409	Email address already registered
`INVALID_PASSWORD`	400	Password does not meet requirements
`INSUFFICIENT_PERMISSIONS`	403	User lacks required permissions
`ACCOUNT_INACTIVE`	403	User account is inactive

Data Models

User Object

typescript

interface User {
  id: string // UUID
  email: string // Unique email address
  firstName: string // User's first name
  lastName: string // User's last name
  role: 'admin' | 'user' | 'viewer' // User role
  status: 'active' | 'inactive' | 'pending' // Account status
  avatar?: string // Profile picture URL
  emailVerified: boolean // Email verification status
  lastLoginAt?: Date // Last login timestamp
  createdAt: Date // Account creation timestamp
  updatedAt: Date // Last update timestamp
  profile?: UserProfile // Extended profile information
  preferences?: UserPreferences // User preferences
}

interface UserProfile {
  bio?: string // User biography
  location?: string // Geographic location
  website?: string // Personal website
  twitter?: string // Twitter handle
  linkedin?: string // LinkedIn profile
  github?: string // GitHub username
}

interface UserPreferences {
  theme: 'light' | 'dark' | 'auto' // UI theme preference
  language: string // Preferred language (ISO 639-1)
  timezone: string // Timezone (IANA)
  notifications: {
    email: boolean // Email notifications
    push: boolean // Push notifications
    marketing: boolean // Marketing emails
  }
}

SDK Examples

JavaScript/TypeScript

typescript

import { SUDIGITALClient } from '@sudigital/client'

const client = new SUDIGITALClient({
  baseURL: 'http://localhost:3001',
  token: 'your-jwt-token',
})

// Get all users
const users = await client.users.list({
  page: 1,
  limit: 10,
  search: 'john',
})

// Create user
const newUser = await client.users.create({
  email: 'jane@example.com',
  password: 'SecurePassword123!',
  firstName: 'Jane',
  lastName: 'Smith',
})

// Get current user
const currentUser = await client.users.me()

// Update user
const updatedUser = await client.users.update('user-id', {
  firstName: 'Updated Name',
})

Python

python

from sudigital import Client

client = Client(
    base_url='http://localhost:3001',
    token='your-jwt-token'
)

# Get all users
users = client.users.list(page=1, limit=10, search='john')

# Create user
new_user = client.users.create({
    'email': 'jane@example.com',
    'password': 'SecurePassword123!',
    'firstName': 'Jane',
    'lastName': 'Smith'
})

# Get current user
current_user = client.users.me()

cURL Examples

bash

# Get all users
curl -X GET "http://localhost:3001/api/users?page=1&limit=10" \
  -H "Authorization: Bearer your-jwt-token"

# Create user
curl -X POST http://localhost:3001/api/users \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "password": "SecurePassword123!",
    "firstName": "Jane",
    "lastName": "Smith"
  }'

# Get current user
curl -X GET http://localhost:3001/api/users/me \
  -H "Authorization: Bearer your-jwt-token"

# Update user
curl -X PUT http://localhost:3001/api/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Updated Name"
  }'

Testing

Test Data

Development environment includes test users:

json

[
  {
    "email": "admin@sudigital.com",
    "password": "admin123",
    "role": "admin"
  },
  {
    "email": "user@sudigital.com",
    "password": "user123",
    "role": "user"
  },
  {
    "email": "viewer@sudigital.com",
    "password": "viewer123",
    "role": "viewer"
  }
]

Postman Collection

Import our Postman collection for comprehensive API testing:

bash

curl -O https://api.sudigital.com/postman/users-collection.json

Rate Limiting

Users API endpoints have the following rate limits:

Endpoint	Limit	Window
`GET /users`	100 requests	1 minute
`POST /users`	10 requests	1 minute
`PUT /users/*`	20 requests	1 minute
`DELETE /users/*`	5 requests	1 minute
`POST /users/*/avatar`	3 requests	1 minute

Best Practices

Security

Password Requirements
- Minimum 8 characters
- Must contain uppercase, lowercase, number, and symbol
- Cannot be common passwords or personal information
Data Validation
- All inputs are validated and sanitized
- Email addresses are verified before activation
- File uploads are scanned and size-limited
Privacy
- Personal data is encrypted at rest
- Sensitive fields are excluded from logs
- GDPR compliance for data deletion

Performance

Pagination
- Always use pagination for list endpoints
- Maximum 100 items per page
- Include total counts for UI pagination
Caching
- User profiles are cached for 5 minutes
- ETags supported for conditional requests
- Cache-Control headers included
Optimization
- Use field selection to reduce payload size
- Batch operations when updating multiple users
- Implement proper indexing for search queries

Authentication API - User authentication and tokens
API Overview - General API information
Quick Start Guide - Getting started

Users API ​

Overview ​

Base URL ​

Authentication ​

Endpoints ​

Get All Users ​

Query Parameters ​

Response ​

Example Request ​

Create User ​

Request Body ​

Required Fields ​

Optional Fields ​

Response ​

Get User by ID ​

Path Parameters ​

Response ​

Update User ​

Request Body ​

Updatable Fields ​

Response ​

Delete User ​

Response ​

Get Current User ​

Response ​

Update Current User ​

Request Body ​

Change User Password ​

Request Body ​

Response ​

Upload User Avatar ​

Request Body ​

Response ​

Get User Activity ​

Query Parameters ​

Response ​

User Roles & Permissions ​

Available Roles ​

Permission Matrix ​

Error Responses ​

Validation Errors ​

Common Error Codes ​

Data Models ​

User Object ​

SDK Examples ​

JavaScript/TypeScript ​

Python ​

cURL Examples ​

Testing ​

Test Data ​

Postman Collection ​

Rate Limiting ​

Best Practices ​

Security ​

Performance ​

Related Resources ​

Users API

Overview

Base URL

Authentication

Endpoints

Get All Users

Query Parameters

Response

Example Request

Create User

Request Body

Required Fields

Optional Fields

Response

Get User by ID

Path Parameters

Response

Update User

Request Body

Updatable Fields

Response

Delete User

Response

Get Current User

Response

Update Current User

Request Body

Change User Password

Request Body

Response

Upload User Avatar

Request Body

Response

Get User Activity

Query Parameters

Response

User Roles & Permissions

Available Roles

Permission Matrix

Error Responses

Validation Errors

Common Error Codes

Data Models

User Object

SDK Examples

JavaScript/TypeScript

Python

cURL Examples

Testing

Test Data

Postman Collection

Rate Limiting

Best Practices

Security

Performance

Related Resources