Core CRUD

Basic user account creation, retrieval, update, and deletion operations.

GET /api/users

Search and filter users with pagination.

Authentication: Required

Query Parameters:

Parameter	Type	Default	Description
q	string	-	Search query (username, givenName, familyName, displayName, email)
sort	string	-	Sort field
limit	integer	30	Results per page
start	integer	0	Pagination offset

Response:

The response is a paginated HAL collection. User items are returned under _embedded["inf:user"].

{
  "_links": {
    "self": { "href": "/api/users{?sort,limit,start,q}", "templated": true }
  },
  "_embedded": {
    "inf:user": [
      {
        "_links": {
          "self": { "href": "/api/users/john.doe" }
        },
        "username": "john.doe",
        "displayName": "John Doe",
        "givenName": "John",
        "familyName": "Doe",
        "email": "john.doe@example.com",
        "enabled": true,
        "avatarUrl": "/api/users/john.doe/avatar?t=1707484800000"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 45
}

---

GET /api/users-list

Get a complete list of users with additional metadata.

Authentication: Required

Response:

Returns an array of users with full details.

---

GET /api/users-content

Get content count statistics for users.

Authentication: Required

Response:

Returns content ownership statistics.

---

POST /api/users

Create a new user account.

Authentication: Required

Permissions: users:create

Request Body:

{
  "username": "jane.smith",
  "password": "initialPassword123",
  "domain": "local",
  "displayName": "Jane Smith",
  "givenName": "Jane",
  "familyName": "Smith",
  "email": "jane.smith@example.com",
  "enabled": false,
  "superuser": false,
  "timezone": "America/New_York",
  "settings": {}
}

Required Fields:

Field	Type	Description
username	string	Unique username
password	string	Initial password

Optional Fields:

Field	Type	Default	Description
domain	string	local	Authentication domain
displayName	string	-	Full name
givenName	string	-	First name
familyName	string	-	Last name
middleName	string	-	Middle name
email	string	-	Email address
enabled	boolean	false	Account enabled status
superuser	boolean	false	Admin privileges (requires requestor to be superuser)
timezone	string	-	User timezone
settings	object	{}	User preferences

Response:

{
  "username": "jane.smith",
  "displayName": "Jane Smith",
  "enabled": false,
  "createdAt": "2024-02-09T10:00:00Z",
  "_links": {
    "self": { "href": "/api/users/jane.smith" }
  }
}

Status Code: 201 Created

---

GET /api/users/{username}

Get a specific user by username.

Authentication: Required

Path Parameters:

Parameter	Type	Description
username	string	Username

Response:

{
  "username": "john.doe",
  "displayName": "John Doe",
  "givenName": "John",
  "familyName": "Doe",
  "email": "john.doe@example.com",
  "domain": "local",
  "enabled": true,
  "superuser": false,
  "timezone": "America/New_York",
  "settings": {},
  "locked": false,
  "loginAttempts": 0,
  "passwordExpiresAt": "2024-06-01T00:00:00Z",
  "avatarUrl": "/api/users/john.doe/avatar?t=1707484800000",
  "createdAt": "2023-01-15T10:00:00Z",
  "updatedAt": "2024-02-08T14:30:00Z",
  "_links": {
    "self": { "href": "/api/users/john.doe" }
  }
}

---

PUT /api/users/{username}

Update a user account.

Authentication: Required

Permissions: user:edit

Path Parameters:

Parameter	Type	Description
username	string	Username

Request Body:

{
  "displayName": "John M. Doe",
  "email": "john.m.doe@example.com",
  "timezone": "America/Los_Angeles",
  "enabled": true
}

Updatable Fields:

Field	Type	Description
username	string	Change username
displayName	string	Display name
givenName	string	First name
familyName	string	Last name
middleName	string	Middle name
email	string	Email address
enabled	boolean	Account status
settings	object	User preferences
timezone	string	Timezone
domain	string	Authentication domain
locked	boolean	Lock status
lockedAt	date	Lock timestamp
loginAttempts	integer	Failed login count
passwordSetAt	date	Password set timestamp
passwordExpiresAt	date	Password expiration

Response:

Returns the updated user object.

Special Behavior:

When changing domain from non-local to local, a password reset email is automatically sent.

---

DELETE /api/users/{username}

Delete a user account.

Authentication: Required

Permissions: user:delete

Path Parameters:

Parameter	Type	Description
username	string	Username

Response:

204 No Content on success.

---

GET /api/me

Get the currently authenticated user's profile.

Authentication: Required

Response:

Returns the current user object with same structure as GET /api/users/{username}.

---

PUT /api/me

Update the currently authenticated user's profile.

Authentication: Required

Request Body:

{
  "displayName": "Updated Name",
  "email": "new.email@example.com",
  "timezone": "America/Chicago"
}

Response:

Returns the updated user object.

Use Case:

Allow users to update their own profile without admin permissions.