diff --git a/docs/client-sdk/javascript/reference.mdx b/docs/client-sdk/javascript/reference.mdx index 3e0312a..5626b51 100644 --- 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 --- +#### + +`hb.addRoles(userIds, roles, exclusive): Promise` + +Adds the list of roles to all the provided user ids. + +**Method parameters** + + + List of user ids + + + + List of roles to be assigned to the provided user ids + + + + If set to true, the roles are assigned to all users except the provided list of user ids. + + +#### + +Removes the list of roles from all the provided user ids. + +`hb.removeRoles(userIds, roles, exclusive): Promise` + +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** + + + List of user ids + + + + List of roles to be removed from the provided user ids + + + + If set to true, the roles are removed from all users except the provided list of user ids. + + #### `hb.setPermissions(userId, permissionData): Promise` +`setPermissions` is deprecated, please use `addRoles` and `removeRoles` + 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 ---- - #### `hb.sendEvent(event): void` @@ -225,8 +267,6 @@ Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. [See exa ---- - #### `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. ---- - #### `hb.ping(): void` diff --git a/docs/guides/roles.mdx b/docs/guides/roles.mdx new file mode 100644 index 0000000..bf1c927 --- /dev/null +++ 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 index 1fb8f49..089a5ee 100644 --- 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 new file mode 100644 index 0000000..f7cf970 --- /dev/null +++ b/docs/rest-api/session/add-roles.mdx @@ -0,0 +1,34 @@ +--- +title: "Add Roles" +api: "POST https:///addRoles" +authMethod: "bearer" +playground: "none" +--- + +## Parameters + +Note that the parameters are provided as an array, as opposed to an object. + + + List of user ids + + + + List of roles to be assigned to the provided user ids + + + + "Exclusive" flag, where if set to true, the roles are assigned to all users *except* the provided list of user ids. + + + + +```bash cURL +curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \ + https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/addRoles -d \ + '[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]' +``` + + + +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 index 5f95203..c2e8066 100644 --- a/docs/rest-api/session/bookmarks.mdx +++ b/docs/rest-api/session/bookmarks.mdx @@ -1,5 +1,8 @@ --- title: "Set Bookmarks" +api: "POST https:///bookmarks" +authMethod: "bearer" +playground: "none" --- diff --git a/docs/rest-api/session/remove-roles.mdx b/docs/rest-api/session/remove-roles.mdx new file mode 100644 index 0000000..ab80c59 --- /dev/null +++ b/docs/rest-api/session/remove-roles.mdx @@ -0,0 +1,34 @@ +--- +title: "Remove Roles" +api: "POST https:///removeRoles" +authMethod: "bearer" +playground: "none" +--- + +## Parameters + +Note that the parameters are provided as an array, as opposed to an object. + + + List of user ids + + + + List of roles to be removed from the provided user ids + + + + "Exclusive" flag, where if set to true, the roles are removed from all users *except* the provided list of user ids. + + + + +```bash cURL +curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \ + https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/removeRoles -d \ + '[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]' +``` + + + +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 index 4185b4d..e326749 100644 --- 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:///setPermissions" +playground: 'none' authMethod: "bearer" +deprecated: true --- +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 + ## Parameters