Update user role

Updates the role, group assignments, and access scope for a specific user within the tenant.

Use this endpoint when a user's responsibilities change and their permissions need to be adjusted — including switching between fixed roles, scoping group access, or assigning a custom RBAC role via AuthZ Role User.

About Update User Role This is the current, supported endpoint for modifying another user's role and access within Esper. It operates on the authn_user_id (UUID format), which is distinct from the integer id returned by GET /user/ — use GET /authn2/v1/users/ to retrieve the correct UUID. The request replaces the user's current role and group assignment in full; partial updates are not supported. Returns the updated User object on success.

Key Fields / Request Body

role — (required) the role to assign: Enterprise Admin, Viewer, Group Admin, Group Viewer, or AuthZ Role User

groups — (required) list of group UUIDs to scope access; can be empty if has_all_group_access is true or the role does not require group scoping

authz_role_id — UUID of the custom RBAC role; required when role is AuthZ Role User

has_all_group_access — set to true to grant access to all groups; required only for AuthZ Role User role type

can_factory_reset — whether the user should be permitted to factory reset devices

Common Use Cases

Promoting a Viewer to Enterprise Admin after a role change

Scoping a user to specific device groups by switching them to Group Admin or Group Viewer

Assigning a custom RBAC role for fine-grained permission control

Revoking broad access by narrowing a user's group list

Best Practices

Use GET /authn2/v1/users/ to retrieve the user's UUID (authn_user_id) before calling this endpoint — the integer id from GET /user/ will not work here

When setting role to AuthZ Role User, always provide both authz_role_id and either a populated groups list or has_all_group_access: true

Treat this as a full replacement of the user's role record — always include all intended group assignments in a single call rather than assuming previous values are preserved

Workflow

Call GET /authn2/v1/users/ to retrieve the target user's UUID (authn_user_id)

Determine the new role, group scope, and any custom RBAC role ID

PUT to this endpoint with the fully populated request body

Confirm the updated role and group assignments in the returned User object