SFTPGo Octri Preview
POST/roles

Create a role

Creates a new role that can be assigned to administrators, users, groups, and folders. Supply a unique name; set resource_isolation to 0 to disable isolation or 1 to enable it, and include settings only when the role needs additional settings. The 201 response returns the created role.

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

9 body fields

Role configuration to create. name identifies the role; omit settings when the role has no additional settings.

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

6 status codes
201Returns the created role object, including its name, settings, resource isolation level, and timestamps.
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
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
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 create a role.
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 create a role. A 500 is returned when the server encounters an error. resource_isolation must be 0 or 1, and name must be unique.