Remove User Role from User

The Remove User Role from User operation removes a specified User Role from a specified user. This operation is not valid for system-defined or pattern-based users.

HTTP method and URI

POST /api/users/{user-id}/operations/remove-user-role

In this request, the URI variable {user-id} is the object ID of the user from which a User Role is to be removed or the special keyword value "this-user" which designates the API user that issued the request.

Request body contents

The request body is expected to contain a JSON object with the following field:

Field name Type Rqd/Opt Description
user-role-uri String/ URI Required The canonical URI path of the User Role to be removed.

Description

This operation removes a User Role from a user.

On successful execution of this operation the User Role specified in the request body has been removed from the user identified in the request URI.

The request body is validated against the schema described in Request body contents. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. If the request URI does not designate an existing User object, status code 404 (Not Found) is returned. If the API user does not have user-related-access permission to the designated User object or action/task permission to the Manage Users or Manage User Templates task, whichever is appropriate, status code 404 (Not Found) is returned. If the API user has user-related-access permission to the designated User object but not action/task permission to the Manage Users or Manage User Templates task, whichever is appropriate, status code 403 (Forbidden) is returned. If the specified object is not in the collection of the user's User Roles, status code 409 (Conflict) is returned. An attempt to update the User Role collection of a system-defined or pattern-based user is not valid and fails with status code 400 (Bad Request).

If this operation changes the value of any property for which property-change notifications are due, those notifications are emitted asynchronously to this operation.

Authorization requirements

This operation has the following authorization requirement:
  • Action/task permission to the Manage Users task to modify a standard user or the Manage User Templates task to modify a template user.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Remove User Role from User: HTTP status and reason codes
HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
314 This operation is not supported for an object of this type. The User Role collection of system-defined and pattern-based users may not be altered.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the correct type.
409 (Conflict) 316 The object designated by the URI in the request body is not in the user's collection of User Roles.
321 The User Role cannot be removed at this time. The user is currently the only locally-authenticated user with permission to the tasks for managing users and user roles.
328

The User Role cannot be removed at this time, because doing so would leave the user without object-access permission to their default group.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Remove User Role from User: Request
POST /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91/operations/remove-user-role HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 73
{
   "user-role-uri":"/api/user-roles/eaecdf34-4a7a-11e4-8777-1c6f65065a91"
}
Figure 2. Remove User Role from User: Response
204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:31 GMT

<No response body>