SFTPGo Octri Preview
POST/groups

Create a group

Creates a new group with its membership, user settings, and virtual folder mappings. Supply name to identify the group and include any group settings or associations you want to configure. A 201 response returns the created group.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 10 body fields
confidential_dataintegeroptional
Set to `1` to include keys and additional data for secrets in the response; this parameter is ignored if the authenticated user does not have the required permission.

Group configuration, including its name, membership, user settings, and virtual folder mappings. name is required.

adminsarray<string>optional
list of admins usernames associated with this group
created_atintegeroptional
Creation time as Unix timestamp in milliseconds.
descriptionstringoptional
Optional free-form description.
idintegeroptional
Server-generated group identifier; this field is read-only.
namestringrequired
Unique group name. Referenced from `User.groups[].name` with a type (primary/secondary/membership).
rolestringoptional
Role name. A group carrying a role with `resource_isolation` enabled is visible to the admins carrying the same role, it is reachable from the accounts of that role and its storage is measured against the allowlist of the role. An admin carrying a role receives that role on the groups it creates. On update the body replaces the stored role: omitting it clears the role, and the change is refused while accounts or admins of another role reference the group
updated_atintegeroptional
Last update time as Unix timestamp in milliseconds.
user_settingsobjectoptional
Settings applied to users in the group, including filesystem, permissions, home directory, session limits, bandwidth, data transfer, and quota settings.
usersarray<string>optional
list of usernames associated with this group
virtual_foldersarray<object>optional
mapping between virtual SFTPGo paths and folders

6 status codes
201Returns the created group, including its name, membership, settings, and virtual folder mappings.
adminsarray<string>optional
list of admins usernames associated with this group
created_atintegeroptional
Creation time as Unix timestamp in milliseconds.
descriptionstringoptional
Optional free-form description.
idintegeroptional
namestringrequired
Unique group name. Referenced from `User.groups[].name` with a type (primary/secondary/membership).
rolestringoptional
Role name. A group carrying a role with `resource_isolation` enabled is visible to the admins carrying the same role, it is reachable from the accounts of that role and its storage is measured against the allowlist of the role. An admin carrying a role receives that role on the groups it creates. On update the body replaces the stored role: omitting it clears the role, and the change is refused while accounts or admins of another role reference the group
updated_atintegeroptional
Last update time as Unix timestamp in milliseconds.
user_settingsobjectoptional
usersarray<string>optional
list of usernames associated with this group
virtual_foldersarray<object>optional
mapping between virtual SFTPGo paths and folders
400Returned when `name` is missing or the group request is invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when authentication is missing or invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the authenticated user is not permitted to create a group.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when the server encounters an internal error.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
defaultUnexpected Error
errorstringoptional
error description if any
messagestringoptional
message, can be empty

Error handling

A 400 is returned when name is missing or the group request is invalid. A 401 is returned when authentication is missing or invalid, and a 403 when the authenticated user is not permitted to create a group. A 500 is returned when the server encounters an internal error.