Users
/api/usersandgroups/users
Annotation based user resource.
The endpoint intentionally keeps the dynamic field data in the model instead of making the set of properties depend on installed plugins. Every value is still converted and validated by its registered UserFieldDefinition. Authentication credentials and session fields are never returned or accepted for mutation.
The UserAccountType#Administrator type is internal and private. It represents the single reserved Master account and cannot be used to create another account through this API.
For an existing user, both PUT and PATCH use partial-update semantics: only properties supplied by the request are changed, while omitted properties retain their current values. PUT is not a full replacement.
GET /api/usersandgroups/users
Lists users visible to the current user, optionally using the existing Users and Groups search syntax.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
query |
query | string |
no | optional Users and Groups search query |
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
array<UserSummary> |
compact summaries of visible users |
Example Request
# Request
GET /api/usersandgroups/users HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"displayName": "string",
"active": true,
"id": "dm4qp19x51ngh8758floe2zfk",
"type": "Administrator"
}
]
POST /api/usersandgroups/users
Creates a new staged user account. The internal Administrator/Master account type is not available for WebAPI account creation.
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
UserCreate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
201 |
application/json |
UserRead |
staged user account |
Example Request
# Request
POST /api/usersandgroups/users HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"fields": {
"property": {
}
},
"type": "Administrator"
}
# Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"fields": {
"property": {
}
},
"type": "Administrator",
"id": "1umn7p0j9bzjtbo8m9z8h26au",
"active": true,
"displayName": "string"
}
Common Error Responses
The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:
{
"status": 404,
"code": "route_not_found",
"message": "The requested API route does not exist.",
"details": []
}
Schemas
Request and response schemas used on this page.
UserSummary
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
active |
boolean |
no | — |
id |
string |
no | — |
type |
string [Administrator, Guest, Standard, Temp] |
no | — |
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
UserCreate
| Property | Type | Required | Description |
|---|---|---|---|
fields |
object |
no |
Applies a complete map of registered field values to the staged model. |
type |
string [Administrator, Guest, Standard, Temp] |
no |
Selects the account type while creating a user. Administrator accounts are internal and the single Master account cannot be created through the WebAPI. |
* |
Object |
no |
Applies one registered field value. |
Object
Type: object
UserRead
| Property | Type | Required | Description |
|---|---|---|---|
fields |
object |
no |
Returns all safe registered field values available for this account. |
type |
string [Administrator, Guest, Standard, Temp] |
no |
Account type. It can only be selected while creating an account. The internal Administrator/Master account type is returned for the existing Master account but cannot be selected for API creation. |
id |
string |
no |
Unique account identifier. |
active |
boolean |
no |
Whether the account is active. |
displayName |
string |
no |
Human-readable account display name. |
lastModified |
number (int64) |
no |
Time of the last persistent modification in milliseconds. |
lastAccess |
number (int64) |
no |
Time of the last successful login in milliseconds. |
* |
Object |
no |
Returns one safe registered field value. |