hyperbeam · philipjscott · Jul 18, 2025 · Jul 18, 2025
diff --git a/docs/client-sdk/javascript/reference.mdx b/docs/client-sdk/javascript/reference.mdx
@@ -176,10 +176,54 @@ Tears down network connections and browser events. Always call this _before_ rem
 
 ---
 
+#### <Heading hidden>addRoles</Heading>
+
+`hb.addRoles(userIds, roles, exclusive): Promise<void>`
+
+Adds the list of roles to all the provided user ids.
+
+**Method parameters**
+
+<ParamField body="userIds" type="string[]" required={true}>
+  List of user ids
+</ParamField>
+
+<ParamField body="roles" type="string[]" required={true}>
+  List of roles to be assigned to the provided user ids
+</ParamField>
+
+<ParamField body="exclusive" type="bool" required={false} default={false}>
+  If set to true, the roles are assigned to all users except the provided list of user ids.
+</ParamField>
+
+#### <Heading hidden>removeRoles</Heading>
+
+Removes the list of roles from all the provided user ids.
+
+`hb.removeRoles(userIds, roles, exclusive): Promise<void>`
+
+Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. [See example.](/client-sdk/javascript/examples#setting-permissions)
+
+**Method parameters**
+
+<ParamField body="userIds" type="string[]" required={true}>
+  List of user ids
+</ParamField>
+
+<ParamField body="roles" type="string[]" required={true}>
+  List of roles to be removed from the provided user ids
+</ParamField>
+
+<ParamField body="exclusive" type="bool" required={false} default={false}>
+  If set to true, the roles are removed from all users except the provided list of user ids.
+</ParamField>
+
 #### <Heading hidden>setPermissions</Heading>
 
 `hb.setPermissions(userId, permissionData): Promise<void>`
 
+<Warning>`setPermissions` is deprecated, please use `addRoles` and `removeRoles`</Warning>
+
 Sets the permission of a user by their ID. The client must have an admin token set to manage user permissions. [See example.](/client-sdk/javascript/examples#setting-permissions)
 
 **Method parameters**
@@ -213,8 +257,6 @@ Sets the permission of a user by their ID. The client must have an admin token s
   </Expandable>
 </ParamField>
 
----
-
 #### <Heading hidden>sendEvent</Heading>
 
 `hb.sendEvent(event): void`
@@ -225,8 +267,6 @@ Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. [See exa
 
 <ParamField body="event" type="KeyEvent | MouseEvent | WheelEvent"></ParamField>
 
----
-
 #### <Heading hidden>resize</Heading>
 
 `hb.resize(width, height): void`
@@ -247,8 +287,6 @@ Resizes the virtual browser to the specified width and height, in pixels. The ar
   The height of the virtual browser in pixels.
 </ParamField>
 
----
-
 #### <Heading hidden>ping</Heading>
 
 `hb.ping(): void`

diff --git a/docs/guides/roles.mdx b/docs/guides/roles.mdx
@@ -0,0 +1,30 @@
+---
+title: "Roles"
+description: ""
+---
+
+Hyperbeam roles are scoped permissions assigned to users. They are similar to Linux groups, where each role corresponds to one permission, and multiple roles can be assigned to a single user.
+
+| Role              | Enabled by default?  | Description                                                                                                  |
+| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `chrome_apis`     | ✅                   | Allows the user to call functions from the Chrome Tabs API (`hb.tabs`)                                       |
+| `resize`          | ✅                   | Allows user to resize the resolution of the Hyperbeam browser                                                |
+| `control`         | ✅                   | Allows the user to send mouse and keyboard inputs                                                            |
+| `cursor_data`     | ❌                   | Provides cursor data of other users via the `onCursor` callback                                              |
+| `clipboard_copy`  | ❌                   | Allows the user to copy content from the browser using CTRL+C / CMD+C                                        |
+| `file_upload`     | ❌                   | Allows the user to upload files from their local file system                                                 |
+| `field_masking`   | ❌                   | Allows the user to write to [masked fields](https://github.com/hyperbeam/examples/tree/master/field-masking) |
+
+## Overriding default roles
+
+You can override the default roles assigned to a newly connected user when creating the session:
+
+```bash
+curl -X POST -H "Authorization: Bearer $HB_API_KEY" \
+  https://engine.hyperbeam.com/v0/vm --data \
+  '{"default_roles": ["control", "clipboard_copy", "cursor_data"]}'
+```
+
+## Toggling roles
+
+You can toggle the roles of individual users dynamically. See [addRoles](/rest-api/session/add-roles) and [removeRoles](/rest-api/session/remove-roles) endpoints.
diff --git a/docs/mint.json b/docs/mint.json
@@ -59,7 +59,8 @@
         "guides/persist-session-state",
         "guides/authenticating-participants",
         "guides/install-chrome-extension",
-        "guides/resize-browser-window"
+        "guides/resize-browser-window",
+        "guides/roles"
       ]
     },
     {
@@ -82,9 +83,11 @@
           "group": "Session API",
           "pages": [
             "rest-api/session/session-overview",
-            "rest-api/session/set-user-permission",
+            "rest-api/session/add-roles",
+            "rest-api/session/remove-roles",
             "rest-api/session/removing-users",
-            "rest-api/session/bookmarks"
+            "rest-api/session/bookmarks",
+            "rest-api/session/set-user-permission"
           ]
         }
       ]

diff --git a/docs/rest-api/session/add-roles.mdx b/docs/rest-api/session/add-roles.mdx
@@ -0,0 +1,34 @@
+---
+title: "Add Roles"
+api: "POST https://<embed_url>/addRoles"
+authMethod: "bearer"
+playground: "none"
+---
+
+## Parameters
+
+Note that the parameters are provided as an array, as opposed to an object.
+
+<ParamField body="0" type="string[]" required={true}>
+  List of user ids
+</ParamField>
+
+<ParamField body="1" type="string[]" required={true}>
+  List of roles to be assigned to the provided user ids
+</ParamField>
+
+<ParamField body="2" type="bool" required={false} default={false}>
+  "Exclusive" flag, where if set to true, the roles are assigned to all users *except* the provided list of user ids.
+</ParamField>
+
+<RequestExample>
+
+```bash cURL
+curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \
+  https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/addRoles -d \
+  '[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]'
+```
+
+</RequestExample>
+
+The request body mirrors the function signature of `addRoles([userIds], [roles], exclusive)` from the [JavaScript SDK.](/client-sdk/javascript)
diff --git a/docs/rest-api/session/bookmarks.mdx b/docs/rest-api/session/bookmarks.mdx
@@ -1,5 +1,8 @@
 ---
 title: "Set Bookmarks"
+api: "POST https://<embed_url>/bookmarks"
+authMethod: "bearer"
+playground: "none"
 ---
 
 <RequestExample>

diff --git a/docs/rest-api/session/remove-roles.mdx b/docs/rest-api/session/remove-roles.mdx
@@ -0,0 +1,34 @@
+---
+title: "Remove Roles"
+api: "POST https://<embed_url>/removeRoles"
+authMethod: "bearer"
+playground: "none"
+---
+
+## Parameters
+
+Note that the parameters are provided as an array, as opposed to an object.
+
+<ParamField body="0" type="string[]" required={true}>
+  List of user ids
+</ParamField>
+
+<ParamField body="1" type="string[]" required={true}>
+  List of roles to be removed from the provided user ids
+</ParamField>
+
+<ParamField body="2" type="bool" required={false} default={false}>
+  "Exclusive" flag, where if set to true, the roles are removed from all users *except* the provided list of user ids.
+</ParamField>
+
+<RequestExample>
+
+```bash cURL
+curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \
+  https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/removeRoles -d \
+  '[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]'
+```
+
+</RequestExample>
+
+The request body mirrors the function signature of `removeRoles([userIds], [roles], exclusive)` from the [JavaScript SDK.](/client-sdk/javascript)
diff --git a/docs/rest-api/session/set-user-permission.mdx b/docs/rest-api/session/set-user-permission.mdx
@@ -1,9 +1,13 @@
 ---
 title: "Set User Permissions"
-api: "POST https://engine.hyperbeam.com/setPermissions"
+api: "POST https://<embed_url>/setPermissions"
+playground: 'none'
 authMethod: "bearer"
+deprecated: true
 ---
 
+<Warning>This endpoint is deprecated, please use [addRoles](https://docs.hyperbeam.com/rest-api/session/add-roles) and [removeRoles](https://docs.hyperbeam.com/rest-api/session/remove-roles) instead</Warning>
+
 ## Parameters
 
 <ParamField body="priority" type="integer" default={0}>