User management

The users module supports self-service account changes and administrative user management. All user routes require a bearer access token. Administrative routes also require a specific effective permission.

The default base path is http://localhost:3000/api/v1/users.

User states

Soft deletion is tracked separately with deletedAt. Administrative user responses may include deleted records when requested.

Self-service operations

Self-service routes need only a valid access token:

Get the current profile:

curl http://localhost:3000/api/v1/users/me \
  --header 'Authorization: Bearer <access-token>'

Update the display name:

curl --request PATCH http://localhost:3000/api/v1/users/me \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Updated Name"
  }'

Request an email change:

curl --request POST http://localhost:3000/api/v1/users/me/email-change \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "newEmail": "updated@example.com",
    "currentPassword": "current-password-at-least-12-characters"
  }'

The email changes only after the recipient submits the verification token through POST /auth/verify-email.

Administrative permissions

The default RBAC seed creates:

The seeded ADMIN role receives all system user permissions. The SUPER_ADMIN role bypasses individual permission checks. Effective permissions can still differ because of per-user overrides.

Administrative operations

Create a managed user

curl --request POST http://localhost:3000/api/v1/users \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "managed@example.com",
    "displayName": "Managed User",
    "password": "managed-password-at-least-12-characters"
  }'

Managed users start as ACTIVE with their initial email marked as verified.

List users

curl \
  'http://localhost:3000/api/v1/users?page=1&limit=20&search=example&status=ACTIVE&includeDeleted=false' \
  --header 'Authorization: Bearer <access-token>'

Supported query fields:

Update status or profile

curl --request PATCH http://localhost:3000/api/v1/users/<user-uuid> \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Managed Account",
    "status": "SUSPENDED"
  }'

Only ACTIVE and SUSPENDED are accepted as administrative status updates. Suspension invalidates existing access by incrementing the user's authentication version.

Soft-delete and restore

curl --request DELETE http://localhost:3000/api/v1/users/<user-uuid> \
  --header 'Authorization: Bearer <access-token>'

curl --request POST http://localhost:3000/api/v1/users/<user-uuid>/restore \
  --header 'Authorization: Bearer <access-token>'

Deletion is soft and invalidates existing authentication. Restoration retains the account record and increments its authentication version again.

Administrative safeguards

• Administrators cannot delete their own account.
• Managed email changes for the acting administrator must use the self-service endpoint.
• RBAC policy prevents callers from managing users whose protected access is outside their authority.
• The final active super administrator cannot be removed through an access replacement.
• Duplicate current or target email addresses return a conflict.

Use Role-Based Access Control to manage assignments and Authentication for verification and session behavior.