Groups
/api/usersandgroups/groups/{groupId}
Exposes groups through the annotation-based WebAPI.
The collection operation deliberately returns compact summaries. A model operation returns only fields whose registered GroupFieldDefinition grants access to the current caller. All mutations are staged on this request-local object and are validated before the first manager write.
For an existing group, 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.
DELETE /api/usersandgroups/groups/{groupId}
Deletes this group. The registered group type restrictions determine whether removal is permitted.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
groupId |
path | string |
yes | group identifier from the URL |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
204 |
— | — | No content. |
Example Request
# Request DELETE /api/usersandgroups/groups/<groupId> HTTP/1.1 Accept: application/json Authorization: Bearer <access-token> # Response HTTP/1.1 204 No Content
GET /api/usersandgroups/groups/{groupId}
Exposes groups through the annotation-based WebAPI.
The collection operation deliberately returns compact summaries. A model operation returns only fields whose registered GroupFieldDefinition grants access to the current caller. All mutations are staged on this request-local object and are validated before the first manager write.
For an existing group, 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.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
groupId |
path | string |
yes | group identifier from the URL |
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
GroupRead |
Successful response. |
Example Request
# Request
GET /api/usersandgroups/groups/<groupId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"fields": {
"property": {
}
},
"permissions": [
"string"
],
"parentId": "dwj0m7iphrmyxrkn3m9j50ek8",
"id": "3pwi6mts1wozoey4bhzypvs65",
"name": "string"
}
PATCH /api/usersandgroups/groups/{groupId}
Exposes groups through the annotation-based WebAPI.
The collection operation deliberately returns compact summaries. A model operation returns only fields whose registered GroupFieldDefinition grants access to the current caller. All mutations are staged on this request-local object and are validated before the first manager write.
For an existing group, 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.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
groupId |
path | string |
yes | group identifier from the URL |
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
GroupUpdate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
GroupRead |
Successful response. |
Example Request
# Request
PATCH /api/usersandgroups/groups/<groupId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"fields": {
"property": {
}
},
"permissions": [
"string"
],
"parentId": "dhn68n9xqgm23k5rp9napmjpo",
"name": "string",
"type": "string"
}
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"fields": {
"property": {
}
},
"permissions": [
"string"
],
"parentId": "dwj0m7iphrmyxrkn3m9j50ek8",
"id": "3pwi6mts1wozoey4bhzypvs65",
"name": "string"
}
PUT /api/usersandgroups/groups/{groupId}
Exposes groups through the annotation-based WebAPI.
The collection operation deliberately returns compact summaries. A model operation returns only fields whose registered GroupFieldDefinition grants access to the current caller. All mutations are staged on this request-local object and are validated before the first manager write.
For an existing group, 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.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
groupId |
path | string |
yes | group identifier from the URL |
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
GroupUpdate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
GroupRead |
Successful response. |
Example Request
# Request
PUT /api/usersandgroups/groups/<groupId> HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"fields": {
"property": {
}
},
"permissions": [
"string"
],
"parentId": "dhn68n9xqgm23k5rp9napmjpo",
"name": "string",
"type": "string"
}
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"fields": {
"property": {
}
},
"permissions": [
"string"
],
"parentId": "dwj0m7iphrmyxrkn3m9j50ek8",
"id": "3pwi6mts1wozoey4bhzypvs65",
"name": "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.
GroupRead
| Property | Type | Required | Description |
|---|---|---|---|
fields |
object |
no |
Returns all readable registered field values without exposing field implementation objects or unavailable values. |
permissions |
array<string> |
no |
Returns the desired direct permissions as stable permission keys. |
parentId |
string |
no |
Parent group identifier, or null for a root group. |
id |
string |
no |
Stable group identifier. It is generated for creates and replaced by the manager's ID. |
name |
string |
no |
Required user-visible group name. |
type |
string |
no |
Registered group type name. It is immutable after creation. |
active |
boolean |
no |
Whether this group is active. Inactive groups cannot be updated. |
lastModified |
number (int64) |
no |
Last modification time in milliseconds since the Unix epoch. |
* |
Object |
no |
Returns one registered field value. This dynamic property is also used by PATCH bodies containing a field key directly. |
Object
Type: object
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
GroupUpdate
| Property | Type | Required | Description |
|---|---|---|---|
fields |
object |
no |
Stages a replacement of registered group field values. |
permissions |
array<string> |
no |
Stages replacement of the direct permissions. |
parentId |
string |
no |
Stages a new parent group. |
name |
string |
no |
Required user-visible group name. |
type |
string |
no |
Registered group type name. It is immutable after creation. |
* |
Object |
no |
Stages one registered group field value. Conversion and validation are delegated to the installed GroupFieldDefinition. |