update_role¶

ManagementApi.update_role(id, role_id, update_role_info, update_attributes=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Update a role

Updates a role’s metadata, permissions or attached users. Only a role manager (or a Super Admin) may call this. The operation has two modes, selected by the update-attributes query parameter: - Full mode (update-attributes omitted or set to “all”): every body property is optional and anything omitted keeps its stored value. An empty body is a valid no-op that still returns 200. - Targeted mode (update-attributes names a comma-separated list): each named attribute must be present in the body and must be truthy. An empty string, empty array or empty object is rejected in this mode even though full mode accepts it. Two restrictions return HTTP 400 with a plain message that carries no error-code prefix, unlike every other error on this API: updating a role whose id begins with “default”, and changing anything other than UsersAttached on a role whose name begins with “SystemRole”. Several input-validation failures are returned as HTTP 500 rather than 400 because the handler raises them as backend exceptions: an empty resulting UsersAttached, RoleManagers not being a subset of UsersAttached, and system-role field restrictions in targeted mode (all ROLE-1009). An unknown role id is also a 500 (IPV-1002).

Parameters:

id (str) – Identifier of the role to update. (required)
role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. Not required when the request carries Super Admin context. (required)
update_role_info (UpdateRoleInfo) – (required)
update_attributes (str) – Selects which attributes to update. Either the literal “all”, or a comma-separated subset of RoleName, RoleDescription, RoleManagers, RolePermissions, SidenavConfig and UsersAttached. Any other value is rejected with IPV-1041. When a subset is given, every named attribute must be present and truthy in the request body, and attributes not named are left untouched.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

UpdateRoleResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: PUT /roles/{id}

Parameter examples¶

Name	In	Example
`id`	path	`"role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"`
`role_id`	header	`"role-admin"`
`update-attributes`	query	`"RolePermissions,UsersAttached"`

Request¶

Full mode, replacing description and permissions

{
  "RoleDescription": "Read access to sales and finance datasets",
  "RolePermissions": [
    "datasets.view",
    "playground.manage"
  ]
}

Targeted mode, used with update-attributes=RolePermissions,UsersAttached

{
  "RolePermissions": [
    "datasets.fullaccess"
  ],
  "UsersAttached": [
    "user1",
    "user2",
    "user3"
  ]
}

Rename the role

{
  "RoleName": "senior-data-analyst"
}

Success (HTTP 200)¶

Role updated.

Request / response example

{
  "Message": "Successfully updated the access role"
}

Errors¶

Documented error codes: GE-1001, IPV-1041, IPV-1008, ROLE-1001, ROLE-1003, AUTH-1002, GE-1060, IPV-1002, ROLE-1009, DB-1002, GE-1008.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}, except for the two system-role restrictions listed below, whose messages carry no error-code prefix. Codes: GE-1001 (empty or unparseable body), IPV-1041 (unknown update-attributes value), IPV-1008 (an attribute named in update-attributes is missing or empty), ROLE-1001 (unrecognised permission), ROLE-1003 (RoleName uses the reserved “SystemRole” prefix), AUTH-1002 (caller is not a role manager), GE-1060 (unknown user).

Caller is not a role manager

{
  "Message": "AUTH-1002 - User is not authorized to perform this operation as they are not a role manager."
}

Unknown value in update-attributes

{
  "Message": "IPV-1041 - Invalid value for update-attributes"
}

Attribute named in update-attributes absent or empty in the body

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - {'RolePermissions'}"
}

Default system role, message has no error-code prefix

{
  "Message": "Failed, User cannot update default system access role"
}

System role field restriction, message has no error-code prefix

{
  "Message": "Failed, User cannot update system role metadata other than users attached to it"
}

HTTP 500

Backend failure, and also several input-validation failures the handler raises as backend exceptions. Codes: IPV-1002 (role id not found), ROLE-1009 (UsersAttached would become empty, RoleManagers is not a subset of UsersAttached, or a system-role field was named in update-attributes), DB-1002 (the update could not be persisted), GE-1008 (generic). Body is {“Message”: “<CODE> - <text>”}.

Role id does not exist

{
  "Message": "IPV-1002 - Invalid RoleId - role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f, resource not found."
}

Update would leave the role with no attached users

{
  "Message": "ROLE-1009 - UsersAttached cannot be empty for a role"
}

RoleManagers not contained in UsersAttached

{
  "Message": "ROLE-1009 - RoleManagers must be a subset of UsersAttached"
}