GET
/roles/{name}Get a role by name
Retrieves the role with the specified name. Use this operation to inspect a role's description, resource isolation level, settings, and associated administrators and users. The response includes the role's creation and update timestamps.
namestringrequired
The name of the role to retrieve.
200Returns the role object, including its name, description, resource isolation level, settings, associated administrators and users, 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`
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 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 retrieve the role.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
404Returned when no role exists with the specified name.
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 is invalid. A 401 is returned when the request is unauthenticated. A 403 is returned when the caller is not permitted to retrieve the role. A 404 is returned when no role exists with the specified name. A 500 is returned when the server encounters an error. The name path parameter must identify an existing role.