User Management

Overview

The User Management API (sgivu-user) provides comprehensive operations for managing users, including CRUD operations, multi-criteria search, status management, and user counts. All endpoints require JWT authentication with specific permissions.

Base URL

https://your-domain.com/v1/users

Create User

POST /v1/users

Registers a new user in the system with domain validations. Authentication: Required Authorization: user:create permission

Request Body

username

string

required

Unique username (no special characters)

password

string

required

Password (must meet strength requirements)

person

object

required

Person information object

person.firstName

string

required

First name

person.lastName

string

required

Last name

person.nationalId

string

required

National identification number

person.email

string

required

Email address

person.phone

string

required

Phone number

roles

array

required

Array of role IDs to assign

enabled

boolean

default:"true"

Whether the user account is enabled

{
  "username": "jperez",
  "password": "SecureP@ss123",
  "person": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "nationalId": "1234567890",
    "email": "[email protected]",
    "phone": "3001234567"
  },
  "roles": [1],
  "enabled": true
}

Response

status

string

Response status (success/error)

message

string

Response message

data

object

Created user object

{
  "status": "success",
  "message": "Usuario creado exitosamente",
  "data": {
    "id": 5,
    "username": "jperez",
    "person": {
      "id": 5,
      "firstName": "Juan",
      "lastName": "Pérez",
      "nationalId": "1234567890",
      "email": "[email protected]",
      "phone": "3001234567"
    },
    "roles": [
      {
        "id": 1,
        "name": "USER",
        "description": "Standard user role"
      }
    ],
    "enabled": true,
    "createdAt": "2026-03-06T10:30:00",
    "updatedAt": "2026-03-06T10:30:00"
  }
}

Status Codes

201 Created - User created successfully
400 Bad Request - Invalid input data
401 Unauthorized - Not authenticated
403 Forbidden - Missing user:create permission

Example

curl -X POST https://your-domain.com/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jperez",
    "password": "SecureP@ss123",
    "person": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "nationalId": "1234567890",
      "email": "[email protected]",
      "phone": "3001234567"
    },
    "roles": [1],
    "enabled": true
  }'

Get User by ID

GET /v1/users/{id}

Retrieves the complete profile of a user. Authentication: Required Authorization: user:read permission

Path Parameters

integer

required

User ID

Response

{
  "id": 1,
  "username": "steven",
  "person": {
    "id": 1,
    "firstName": "Steven",
    "lastName": "Rodriguez",
    "nationalId": "1234567890",
    "email": "[email protected]",
    "phone": "3001234567"
  },
  "roles": [
    {
      "id": 1,
      "name": "ADMIN",
      "description": "Administrator role with full permissions"
    }
  ],
  "enabled": true,
  "createdAt": "2026-01-01T00:00:00",
  "updatedAt": "2026-03-01T12:00:00"
}

Status Codes

200 OK - User found
401 Unauthorized - Not authenticated
404 Not Found - User does not exist

Example

curl -X GET https://your-domain.com/v1/users/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

List Users (Paginated)

GET /v1/users/page/{page}

Retrieves a paginated list of users (10 per page). Authentication: Required Authorization: user:read permission

Path Parameters

page

integer

required

Page number (0-based)

Response

{
  "content": [
    {
      "id": 1,
      "username": "steven",
      "person": {
        "firstName": "Steven",
        "lastName": "Rodriguez",
        "email": "[email protected]"
      },
      "roles": ["ADMIN"],
      "enabled": true
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 25,
  "totalPages": 3,
  "last": false
}

Example

curl -X GET https://your-domain.com/v1/users/page/0 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update User

PUT /v1/users/{id}

Updates an existing user profile. Users can edit their own profile, or admins can modify any user with user:update permission. Authentication: Required Authorization: user:update permission OR own user ID

Path Parameters

integer

required

User ID to update

Request Headers

X-User-ID

string

required

Authenticated user ID (injected by Gateway)

Request Body

person

object

Person information to update

roles

array

Array of role IDs (admin only)

enabled

boolean

Account enabled status (admin only)

{
  "person": {
    "firstName": "Juan",
    "lastName": "Pérez García",
    "email": "[email protected]",
    "phone": "3009876543"
  }
}

Response

{
  "status": "success",
  "message": "Usuario actualizado exitosamente",
  "data": {
    "id": 5,
    "username": "jperez",
    "person": {
      "firstName": "Juan",
      "lastName": "Pérez García",
      "email": "[email protected]"
    },
    "updatedAt": "2026-03-06T11:45:00"
  }
}

Status Codes

200 OK - User updated successfully
400 Bad Request - Invalid input
401 Unauthorized - Not authenticated
403 Forbidden - Missing permission or not own user
404 Not Found - User does not exist

Example

curl -X PUT https://your-domain.com/v1/users/5 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person": {
      "email": "[email protected]"
    }
  }'

Delete User

DELETE /v1/users/{id}

Permanently deletes a user from the system. Authentication: Required Authorization: user:delete permission

Path Parameters

integer

required

User ID to delete

Status Codes

204 No Content - User deleted successfully
401 Unauthorized - Not authenticated
403 Forbidden - Missing user:delete permission
404 Not Found - User does not exist

Example

curl -X DELETE https://your-domain.com/v1/users/5 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update User Status

PATCH /v1/users/{id}/status

Enables or disables a user account to control access. Authentication: Required Authorization: user:update permission

Path Parameters

integer

required

User ID

Request Body

enabled

boolean

required

New status (true=enabled, false=disabled)

true

Response

{
  "enabled": true
}

Example

curl -X PATCH https://your-domain.com/v1/users/5/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d 'false'

Get User Counts

GET /v1/users/count

Retrieves statistics: total users, active, and inactive. Authentication: Required Authorization: user:read permission

Response

{
  "total": 25,
  "active": 22,
  "inactive": 3
}

Example

curl -X GET https://your-domain.com/v1/users/count \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Users

GET /v1/users/search

Multi-criteria search with optional filters (AND logic). Authentication: Required Authorization: user:read permission

Query Parameters

name

string

Filter by first or last name (partial match)

username

string

Filter by username (partial match)

string

Filter by email

role

string

Filter by role name

enabled

boolean

Filter by enabled status

Response

[
  {
    "id": 1,
    "username": "steven",
    "person": {
      "firstName": "Steven",
      "lastName": "Rodriguez"
    },
    "roles": ["ADMIN"],
    "enabled": true
  }
]

Example

curl -X GET "https://your-domain.com/v1/users/search?role=ADMIN&enabled=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Users (Paginated)

GET /v1/users/search/page/{page}

Paginated variant of multi-criteria search. Authentication: Required Authorization: user:read permission

Path Parameters

page

integer

required

Page number (0-based)

Query Parameters

size

integer

default:"10"

Page size

name

string

Filter by name

username

string

Filter by username

string

Filter by email

role

string

Filter by role

enabled

boolean

Filter by status

Response

{
  "content": [...],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 5,
  "totalPages": 1
}

Example

curl -X GET "https://your-domain.com/v1/users/search/page/0?size=20&role=USER" \
  -H "Authorization: Bearer YOUR_TOKEN"

Internal Endpoints

Get User by Username

GET /v1/users/username/{username}

This endpoint is for internal service-to-service communication only. It requires the X-Internal-Service-Key header and should never be exposed publicly.

Used by the Authorization Server to retrieve user profile (roles/permissions) when issuing JWT tokens. Authentication: X-Internal-Service-Key header

Path Parameters

username

string

required

Username to look up

Example

curl -X GET https://your-domain.com/v1/users/username/steven \
  -H "X-Internal-Service-Key: YOUR_INTERNAL_KEY"

Authentication

User Management

Vehicle Management

Client Management

Purchase & Sales

Machine Learning

​Overview

​Base URL

​Create User

​Request Body

​Response

​Status Codes

​Example

​Get User by ID

​Path Parameters

​Response

​Status Codes

​Example

​List Users (Paginated)

​Path Parameters

​Response

​Example

​Update User

​Path Parameters

​Request Headers

​Request Body

​Response

​Status Codes

​Example

​Delete User

​Path Parameters

​Status Codes

​Example

​Update User Status

​Path Parameters

​Request Body

​Response

​Example

​Get User Counts

​Response

​Example

​Search Users

​Query Parameters

​Response

​Example

​Search Users (Paginated)

​Path Parameters

​Query Parameters

​Response

​Example

​Internal Endpoints

​Get User by Username

​Path Parameters

​Example

Build docs developers (and LLMs) love

Overview

Base URL

Create User

Request Body

Response

Status Codes

Example

Get User by ID

Path Parameters

Response

Status Codes

Example

List Users (Paginated)

Path Parameters

Response

Example

Update User

Path Parameters

Request Headers

Request Body

Response

Status Codes

Example

Delete User

Path Parameters

Status Codes

Example

Update User Status

Path Parameters

Request Body

Response

Example

Get User Counts

Response

Example

Search Users

Query Parameters

Response

Example

Search Users (Paginated)

Path Parameters

Query Parameters

Response

Example

Internal Endpoints

Get User by Username

Path Parameters

Example