SFTPGo Octri Preview
PUT/roles/{name}

Replace a role configuration

Replaces the configuration of an existing role. Supply the required name and the role settings to apply; resource_isolation accepts 0 or 1, and settings can hold additional role configuration. The admins and users fields are set on read and are not writable role settings.

1 parameter · 9 body fields
namestringrequired
The name of the role to replace.

Role configuration to apply. The name field is required; admins and users are set on read.

adminsarray<string>optional
list of admin usernames carrying this role, set on read
created_atintegeroptional
creation time as unix timestamp in milliseconds
descriptionstringoptional
optional description
idintegeroptional
Read-only role identifier.
namestringoptional
name is unique
resource_isolationintegeroptional
Resource isolation level: * `0` - disabled * `1` - enabled. The groups and folders carrying the role are the ones its admins read, an account reaches the groups and folders of its own role, and the storage allowlist is enforced on every save. It requires `settings.storage_allowlist.local.users_base_dir`. Supported data providers: MySQL, MariaDB, PostgreSQL, CockroachDB, SQLite. The number of roles that can enable it is licensed, see `LicenseFeatures.isolated_roles`
Allowed:01
settingsobjectoptional
Additional settings of a role. Omit it when the role carries none
updated_atintegeroptional
last update time as unix timestamp in milliseconds
usersarray<string>optional
list of usernames carrying this role, set on read

7 status codes
200Returns a response object with an `error` description, if any, and a `message` that can be empty.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
400Returned when the request body is invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when the request is unauthenticated.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the caller is not permitted to update the role.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
404Returned when the role does not exist.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when the server encounters an 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 the request body is invalid. A 401 is returned when the request is unauthenticated. A 403 is returned when the caller is not permitted to update the role. A 404 is returned when the role does not exist. A 500 is returned when the server encounters an error. The name path parameter identifies the role, and the body name field is required; resource_isolation must be 0 or 1.