Update a role

PUT 
/roles/:id

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).

Request

Responses

200

Role updated.

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

400

Input validation or authorization failure. Body is {"Message": " - "}, 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).

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

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": " - "}.

Response Headers

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers