Delete an environment role

DELETE /v1/roles/{role_id} · permission roles:write

Deletes the role. With force=true an assigned role is deleted too and its membership assignments are removed in the same operation; otherwise an assigned role returns 409 role_in_use. A role used as an organization's admin or default member role is never deleted. If-Match is optional. The deletion is audited as role.deleted.

Request

Field	Type	Required	Description
`role_id`	path	yes	Role ID (`rol_…`).
`force`	query	no	`true` also removes the role's assignments; `false` (default) refuses an assigned role.
`If-Match`	header	no	Current `ETag`; on mismatch `412`.

No request body.

Response

204 No Content.

Errors

HTTP	code	When
404	`not_found`	The role does not exist in this scope.
409	`role_in_use`	The role is assigned and `force` is not `true`, or it is an organization's admin or default member role.
412	`precondition_failed`	`If-Match` does not match the current version.
422	`validation_failed`	`force` is not `true` or `false`, or is repeated.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	A dependency is temporarily unavailable; retry after the `Retry-After` period.

Example

curl -i -X DELETE "https://api.eu.keenauth.com/v1/roles/rol_01j9xr7s1t2w6x8y0z2a4b6c8e?force=true" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"