Delete a group
DELETE/groups/:groupName
Deletes a group outright. There is no soft delete, no archive and no
undo, and re-creating the same name afterwards produces a new group with
a new id.
The one guard is a check for AWS access. If any permission set is
assigned to the group, the deletion is refused with a 409 and nothing is
removed. List the assignments with GET /groups/{groupName}/assignments,
clear each with DELETE /permission-set-assignments/{id}, and retry.
Two things to know before relying on that guard:
- It counts every permission set assignment recorded against the
group, including ones this API will not show you. An assignment whose
permission set no longer exists is dropped from
GET /groups/{groupName}/assignmentsbut is still counted here, so the 409 can name more assignments than that list contains. A count you cannot reconcile is this, not a bug in your code. - It is a check Prism performs before calling the directory, not a constraint the directory enforces, and it depends on Prism's own database being reachable while the request runs. Treat it as a safety net rather than a guarantee.
Deleting the group removes it from the directory together with every membership in it. The members themselves are untouched, but they lose whatever the group was giving them. Prism's own records that reference the group by name are not cleaned up: custom application assignments made to it are left behind, pointing at a group that no longer exists.
The operation is not idempotent: a second DELETE of the same name
returns 404. It answers 200 with a body, not 204, and that body
echoes the name rather than the deleted group. Fetch the group first if
you want a copy of it.
Request
Responses
- 200
- 401
- 403
- 404
- 409
- 500
The group was deleted.
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.
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.
No group in your tenant has this name, so nothing was deleted. A
repeated DELETE lands here. The lookup behind it is the same
bounded search GET /groups/{groupName} uses, with the same caveat.
The group still has permission set assignments and nothing was deleted. The group and its members are untouched and still hold that access.
The message names how many assignments are in the way, but not
which ones. List them with GET /groups/{groupName}/assignments,
bearing in mind the counting caveat above. The error field is the
fixed literal string group has active assignments, which is the
closest thing to a machine-readable marker this response carries;
there is no code field.
The assignment check or the deletion itself failed. Read error to
tell a database problem from a directory one.