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
- Mock serverhttps://api.esper.io/_mock/openapi/authz2/v1/users/{user_id}
- https://develop-api.esper.cloud/apihttps://develop-api.esper.cloud/api/authz2/v1/users/{user_id}
curl -i -X PUT \
'https://api.esper.io/_mock/openapi/authz2/v1/users/{user_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"authz_role_id": "c85d5e04-56ba-49f9-8ef1-94165471fa4c",
"can_factory_reset": true,
"has_all_group_access": true,
"groups": [
"string"
],
"role": "Shoonya Admin"
}'User Updated Successfully
{ "id": 0, "username": "string", "email": "user@example.com", "first_name": "string", "last_name": "string", "full_name": "string", "is_staff": true, "is_superuser": true, "is_active": true, "profile": { "id": 0, "enterprise_user_id": "string", "authn_user_id": "77ba949a-db0b-4544-a77c-b27f70fe06cd", "authn_connection_id": "500f8424-a17b-4138-9b34-dcf4c445232c", "authz_role_id": "c85d5e04-56ba-49f9-8ef1-94165471fa4c", "role": "Shoonya Admin", "enterprise": "796caaf9-a7de-4817-9ffa-39d04bf83de9", "is_customer": true, "is_endpoint_creator": true, "created_on": "2019-08-24T14:15:22Z", "updated_on": "2019-08-24T14:15:22Z", "setup_wizard_complete": true, "default_password_changed": true, "is_developer": true, "can_factory_reset": true, "groups": [ … ] }, "emm": { "id": 0, "user": 0, "account_identifier": "string", "account_type": "string", "display_name": "string", "google_user_id": "string", "google_enterprise": 0, "is_active": true, "created_on": "2019-08-24T14:15:22Z", "updated_on": "2019-08-24T14:15:22Z", "authentication_token": { … } }, "last_login": "string", "token": "string", "has_emm": true, "is_email_verified": true }