Remove members from a group

DELETE 
/groups/:groupName/members

Removes users from a group.

This DELETE requires a JSON request body and fails without one. The users to remove are named in the body, not in the URL; there is no DELETE /groups/{groupName}/members/{username} to call instead. A request sent with no body is refused with a 400 Invalid request body, and so is one whose body is empty or malformed. The body to send is {"users": ["jdoe"]}, with Content-Type: application/json.

A DELETE that carries a body is unusual, and tooling makes it easy to get wrong: many HTTP clients drop the body on a DELETE by default, and some generated SDKs will not send one at all. If this call keeps answering 400 with a URL you are sure of, check that your client is actually transmitting the body before looking anywhere else. With curl you need -X DELETE together with -d and an explicit -H 'Content-Type: application/json'.

This revokes AWS access. Everyone removed loses every permission set the group grants, immediately and without notice. Access they hold through a direct assignment or through another group is unaffected. Use GET /users/{username}/effective-assignments to see what a person is left with.

Identify users by their directory username, not their email address.

The response echoes your request, not the result. usersRemoved is the array you sent, returned verbatim, and count is its length. Note the key, since the POST on this path answers with usersAdded instead. Neither says which removals actually happened; confirm with GET /groups/{groupName}/members.

The operation is not atomic. Users are removed one at a time and the failures are collected and reported together at the end, so a 500 can mean some were removed and some were not. Re-sending the whole list is the usual way to recover.

A group name that matches nothing is a 500 here, not a 404, unlike GET on the same path.

A body of {} or {"users": null} is accepted rather than rejected: nothing is removed and the response is a 200 with usersRemoved: null and count: 0. That is the one case where sending a body but no users is not an error.

Request

Responses

200

The request was processed. Every name you sent is echoed back whether or not it was removed; see the note above.

400

The request body was missing or was not valid JSON, and nothing was removed. A DELETE sent with no body at all lands here; this is the most common cause.

401

Authentication failed: the X-API-Token header was missing, malformed, expired or not recognised.

This response is text/plain, not JSON. It is written by http.Error in the authentication middleware, which runs before any handler and therefore before anything that would build a JSON envelope. A client that unconditionally JSON-parses response bodies will fail on this one, so check the status code first.

403

The token is valid, but it is not allowed to act on this tenant.

An API token is minted inside one tenant and stays bound to it for life. Sending it to a path whose tenant segment names a different tenant is refused here, in middleware, before the operation runs, so this says nothing about the resource you asked for, only about which tenant the path named. Check the tenant server variable against the console the token was created in.

404

No tenant matches the tenant segment of the request path. A group that does not exist is not reported here; that is a 500.

500

One or more users could not be removed. This single status covers a group that does not exist, a username that matches no user, and a failure in the directory itself. Read error to tell them apart; where individual users failed it names each one. Some of the other users may have been removed; the operation does not roll back.