Roles

$envless->roles->update()

Change a custom role name, description or permissions

php
/**
 * @param RolePatch $patch
 * @return RoleResource
 */
public function update(
    string $id,
    array $patch,
    int|float|null $timeout = null,
): array

Patches a custom role. Every field is optional, but $patch['permissions'] is a full replacement rather than a merge: send the complete list the role should end up with, or leave the key out entirely to keep the current one. Passing 'description' => null clears the description.

System roles are immutable. Patching owner, admin or viewer fails with 409 role.immutable however harmless the field, so gate the call on isSystem. The same two ceilings as creation apply to the permission list: the never assignable permissions fail validation with 400 request.body_invalid, and anything the key owner does not hold themselves fails with 403 auth.permission_denied.

A permission change is live immediately for every member holding the role. Existing API keys owned by those members are not re-clamped by this call, only by a change to the member role, so a key can keep a scope its owner no longer has until that key is updated.

Example

php
use Envless\Envless;

$envless = new Envless();

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

if ($role !== null) {
    $updated = $envless->roles->update($role['id'], [
        'description' => null,
        'permissions' => [
            'projects:read',
            'environments:read',
            'variables:read',
        ],
    ]);

    echo implode(', ', $updated['permissions']), PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$idstringYesRole id from $envless->roles->list(), which must belong to a custom role.
$patchRolePatchYesThe fields below, as one array.
$patch['name']stringNoNew display name, still subject to case insensitive uniqueness.
$patch['description']string|nullNoNew description, or null to clear the existing one.
$patch['permissions']list<string>NoComplete replacement permission list, not a set of additions.
$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

RoleResource reflecting the stored role after the patch.

Worth knowing

  • Sending 'permissions' => [] strips every permission from the role, which is very different from omitting the key.
  • Read the role back with get before patching if you intend to add one permission, since you have to resend the ones you want to keep.
  • A successful patch emits the role.updated webhook event.

Required scopes

roles:write

Underlying endpoint

PATCH /roles/{id}

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

In TypeScript

envless.roles.update()

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