Roles

$envless->roles->delete()

Delete an unused custom role

php
/** @return DeletedRoleResource */
public function delete(string $id, int|float|null $timeout = null): array

Soft deletes a custom role and returns a small receipt holding the id and name that were removed. The id is never reused, and the role reads as 404 from then on.

The role has to be unused. Reassign every member holding it with $envless->members->update() and revoke every pending invite that references it with $envless->invites->revoke() first, otherwise the call is refused with 409 role.in_use and the message tells you how many members or invites are in the way. System roles can never be deleted and fail with 409 role.immutable.

Example

php
use Envless\Envless;

$envless = new Envless();

$role = $envless->roles->listAll(search: 'deploy')[0] ?? null;

if ($role !== null) {
    $removed = $envless->roles->delete($role['id']);

    echo $removed['name'], PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$idstringYesRole id from $envless->roles->list(), which must be a custom role with no members and no pending invites.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

Returns

DeletedRoleResource carrying only the id and name of the removed role.

Worth knowing

  • The response omits permissions, description and the timestamps, so read anything you want to keep with get before deleting.
  • Members are counted before invites, so a role blocked by both reports the member count first and the invite count only after you clear the members.
  • Deleting a role emits the role.deleted webhook event.

Required scopes

roles:write

Underlying endpoint

DELETE /roles/{id}

Request and response schema, every error code, and a live playground.

In TypeScript

envless.roles.delete()

The same method in @goenvless/sdk, with the same request, retries and errors.