def update(
id: str,
patch: RolePatch,
*,
timeout: float | None = None,
) -> RoleResourceasync def update(
id: str,
patch: RolePatch,
*,
timeout: float | None = None,
) -> RoleResourcePatches 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': None 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
from envless import envless
role = envless.roles.list_all(search='deploy')[0]
updated = envless.roles.update(
role['id'],
{
'description': None,
'permissions': [
'projects:read',
'environments:read',
'variables:read',
],
},
)
print(updated['permissions'])import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
role = (await envless.roles.list_all(search='deploy'))[0]
updated = await envless.roles.update(
role['id'],
{
'description': None,
'permissions': [
'projects:read',
'environments:read',
'variables:read',
],
},
)
print(updated['permissions'])
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | Yes | Role id from roles.list, which must belong to a custom role. |
patch['name'] | str | No | New display name, still subject to case insensitive uniqueness. |
patch['description'] | str | None | No | New description, or None to clear the existing one. |
patch['permissions'] | list[str] | No | Complete replacement permission list, not a set of additions. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. 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
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.