PUT
Edit a role (organization)
Organization space User accounts only For: Administrator · Permission: roles.update Conditions
  • A built-in role cannot be changed.
  • name, when sent, is at most 255 characters, lowercased and unique among the roles of the space (the role itself is ignored).
  • permissions, when sent, must be distinct permission group ids valid for the space.
What else happens
  • When permissions is sent, the role’s permissions are replaced by the list (an empty list removes them all).
  • Omitted fields keep their value; description cannot be cleared because null keeps the current one.
Part of Define access profiles and roles.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

role
string
required

Identifier of the role: its group id (27-character KSUID), shared by the per-guard rows of the role.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, name, description, is_builtin, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: permissions.

Response

Resource (only with response=resource).

id

Identifier of the role: its group id (27-character KSUID).

name

Name of the role, stored in lowercase and unique within its space.

description

Optional description, at most 255 characters.

is_builtin
boolean

True for roles created by the system; they cannot be edited or deleted.

permissions
array

Permissions granted by the role. Present only when the include permissions is requested.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).