Skip to content

Commit 1c3efa8

Browse files
philipjscottphilipjscott
authored
Merge pull request #68 from hyperbeam/scotty/roles-hb
add roles docs
2 parents 320fff4 + ba16801 commit 1c3efa8

File tree

7 files changed

+156
-10
lines changed

7 files changed

+156
-10
lines changed

‎docs/client-sdk/javascript/reference.mdx‎

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -176,10 +176,54 @@ Tears down network connections and browser events. Always call this _before_ rem
176176

177177
---
178178

179+
#### <Heading hidden>addRoles</Heading>
180+
181+
`hb.addRoles(userIds, roles, exclusive): Promise<void>`
182+
183+
Adds the list of roles to all the provided user ids.
184+
185+
**Method parameters**
186+
187+
<ParamField body="userIds" type="string[]" required={true}>
188+
List of user ids
189+
</ParamField>
190+
191+
<ParamField body="roles" type="string[]" required={true}>
192+
List of roles to be assigned to the provided user ids
193+
</ParamField>
194+
195+
<ParamField body="exclusive" type="bool" required={false} default={false}>
196+
If set to true, the roles are assigned to all users except the provided list of user ids.
197+
</ParamField>
198+
199+
#### <Heading hidden>removeRoles</Heading>
200+
201+
Removes the list of roles from all the provided user ids.
202+
203+
`hb.removeRoles(userIds, roles, exclusive): Promise<void>`
204+
205+
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)
206+
207+
**Method parameters**
208+
209+
<ParamField body="userIds" type="string[]" required={true}>
210+
List of user ids
211+
</ParamField>
212+
213+
<ParamField body="roles" type="string[]" required={true}>
214+
List of roles to be removed from the provided user ids
215+
</ParamField>
216+
217+
<ParamField body="exclusive" type="bool" required={false} default={false}>
218+
If set to true, the roles are removed from all users except the provided list of user ids.
219+
</ParamField>
220+
179221
#### <Heading hidden>setPermissions</Heading>
180222

181223
`hb.setPermissions(userId, permissionData): Promise<void>`
182224

225+
<Warning>`setPermissions` is deprecated, please use `addRoles` and `removeRoles`</Warning>
226+
183227
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)
184228

185229
**Method parameters**
@@ -213,8 +257,6 @@ Sets the permission of a user by their ID. The client must have an admin token s
213257
</Expandable>
214258
</ParamField>
215259

216-
---
217-
218260
#### <Heading hidden>sendEvent</Heading>
219261

220262
`hb.sendEvent(event): void`
@@ -225,8 +267,6 @@ Sends a keyboard, mouse, or mouse wheel event to the Hyperbeam browser. [See exa
225267

226268
<ParamField body="event" type="KeyEvent | MouseEvent | WheelEvent"></ParamField>
227269

228-
---
229-
230270
#### <Heading hidden>resize</Heading>
231271

232272
`hb.resize(width, height): void`
@@ -247,8 +287,6 @@ Resizes the virtual browser to the specified width and height, in pixels. The ar
247287
The height of the virtual browser in pixels.
248288
</ParamField>
249289

250-
---
251-
252290
#### <Heading hidden>ping</Heading>
253291

254292
`hb.ping(): void`

‎docs/guides/roles.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Roles"
3+
description: ""
4+
---
5+
6+
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.
7+
8+
| Role | Enabled by default? | Description |
9+
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
10+
| `chrome_apis` | ✅ | Allows the user to call functions from the Chrome Tabs API (`hb.tabs`) |
11+
| `resize` | ✅ | Allows user to resize the resolution of the Hyperbeam browser |
12+
| `control` | ✅ | Allows the user to send mouse and keyboard inputs |
13+
| `cursor_data` | ❌ | Provides cursor data of other users via the `onCursor` callback |
14+
| `clipboard_copy` | ❌ | Allows the user to copy content from the browser using CTRL+C / CMD+C |
15+
| `file_upload` | ❌ | Allows the user to upload files from their local file system |
16+
| `field_masking` | ❌ | Allows the user to write to [masked fields](https://github.com/hyperbeam/examples/tree/master/field-masking) |
17+
18+
## Overriding default roles
19+
20+
You can override the default roles assigned to a newly connected user when creating the session:
21+
22+
```bash
23+
curl -X POST -H "Authorization: Bearer $HB_API_KEY" \
24+
https://engine.hyperbeam.com/v0/vm --data \
25+
'{"default_roles": ["control", "clipboard_copy", "cursor_data"]}'
26+
```
27+
28+
## Toggling roles
29+
30+
You can toggle the roles of individual users dynamically. See [addRoles](/rest-api/session/add-roles) and [removeRoles](/rest-api/session/remove-roles) endpoints.

‎docs/mint.json‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,8 @@
5959
"guides/persist-session-state",
6060
"guides/authenticating-participants",
6161
"guides/install-chrome-extension",
62-
"guides/resize-browser-window"
62+
"guides/resize-browser-window",
63+
"guides/roles"
6364
]
6465
},
6566
{
@@ -82,9 +83,11 @@
8283
"group": "Session API",
8384
"pages": [
8485
"rest-api/session/session-overview",
85-
"rest-api/session/set-user-permission",
86+
"rest-api/session/add-roles",
87+
"rest-api/session/remove-roles",
8688
"rest-api/session/removing-users",
87-
"rest-api/session/bookmarks"
89+
"rest-api/session/bookmarks",
90+
"rest-api/session/set-user-permission"
8891
]
8992
}
9093
]

‎docs/rest-api/session/add-roles.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Add Roles"
3+
api: "POST https://<embed_url>/addRoles"
4+
authMethod: "bearer"
5+
playground: "none"
6+
---
7+
8+
## Parameters
9+
10+
Note that the parameters are provided as an array, as opposed to an object.
11+
12+
<ParamField body="0" type="string[]" required={true}>
13+
List of user ids
14+
</ParamField>
15+
16+
<ParamField body="1" type="string[]" required={true}>
17+
List of roles to be assigned to the provided user ids
18+
</ParamField>
19+
20+
<ParamField body="2" type="bool" required={false} default={false}>
21+
"Exclusive" flag, where if set to true, the roles are assigned to all users *except* the provided list of user ids.
22+
</ParamField>
23+
24+
<RequestExample>
25+
26+
```bash cURL
27+
curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \
28+
https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/addRoles -d \
29+
'[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]'
30+
```
31+
32+
</RequestExample>
33+
34+
The request body mirrors the function signature of `addRoles([userIds], [roles], exclusive)` from the [JavaScript SDK.](/client-sdk/javascript)

‎docs/rest-api/session/bookmarks.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
---
22
title: "Set Bookmarks"
3+
api: "POST https://<embed_url>/bookmarks"
4+
authMethod: "bearer"
5+
playground: "none"
36
---
47

58
<RequestExample>

‎docs/rest-api/session/remove-roles.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Remove Roles"
3+
api: "POST https://<embed_url>/removeRoles"
4+
authMethod: "bearer"
5+
playground: "none"
6+
---
7+
8+
## Parameters
9+
10+
Note that the parameters are provided as an array, as opposed to an object.
11+
12+
<ParamField body="0" type="string[]" required={true}>
13+
List of user ids
14+
</ParamField>
15+
16+
<ParamField body="1" type="string[]" required={true}>
17+
List of roles to be removed from the provided user ids
18+
</ParamField>
19+
20+
<ParamField body="2" type="bool" required={false} default={false}>
21+
"Exclusive" flag, where if set to true, the roles are removed from all users *except* the provided list of user ids.
22+
</ParamField>
23+
24+
<RequestExample>
25+
26+
```bash cURL
27+
curl -X POST -H 'Authorization: Bearer $HB_API_KEY' \
28+
https://8e9hs553xoluse47mck4rfxrp.hyperbeam.com/BUPA9uQeTQ2SLRRQZfe0Xg/removeRoles -d \
29+
'[["32670ca3-ffe6-4ff6-ae88-be0ef6709784"], ["control"]]'
30+
```
31+
32+
</RequestExample>
33+
34+
The request body mirrors the function signature of `removeRoles([userIds], [roles], exclusive)` from the [JavaScript SDK.](/client-sdk/javascript)

‎docs/rest-api/session/set-user-permission.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
---
22
title: "Set User Permissions"
3-
api: "POST https://engine.hyperbeam.com/setPermissions"
3+
api: "POST https://<embed_url>/setPermissions"
4+
playground: 'none'
45
authMethod: "bearer"
6+
deprecated: true
57
---
68

9+
<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>
10+
711
## Parameters
812

913
<ParamField body="priority" type="integer" default={0}>

0 commit comments

Comments
 (0)