def update(id, patch = nil, timeout: nil, **fields)def update: (
String id,
?(role_patch | Hash[Symbol | String, untyped])? patch,
?timeout: seconds?,
**untyped
) -> role_resourcePatches a custom role. Every field is optional, but 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: nil 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
require "envless/sdk"
role = Envless.roles.list_all(search: "deploy").fetch(0)
updated = Envless.roles.update(
role[:id],
description: nil,
permissions: %w[projects:read environments:read variables:read]
)
puts updated[:permissions]Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | String | Yes | Role id from roles.list, which must belong to a custom role. |
patch | role_patch | No | The fields below as one Hash, with Symbol or String keys, in place of the keywords. |
name: | String | No | New display name, still subject to case insensitive uniqueness. |
description: | String | nil | No | New description, or nil to clear the existing one. |
permissions: | Array[String] | No | Complete replacement permission list, not a set of additions. |
timeout: | Integer | Float | Rational | No | Seconds each attempt of this call may take, redirects and the response body included, before it raises Envless::NetworkError with timeout? set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
role_resource 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
getbefore 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.updatedwebhook 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.