Update permission docs

docusaurus/video/docusaurus/docs/api/call_types/permissions.mdx

@@ -8,6 +8,16 @@ title: Permissions
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+This page shows how you can create or update roles for a call type. For a conceptual overview about roles please see the [Permissions page](../../moderation/permissions/).
+
+When you create a call type you can specify your role configurations. A role configuration consists of a role name and the list of capabilities that are enabled for that role.
+
+When you create a call type it comes with a default set of configuration. You can override or extend that.
+
+The following example overrides the capabilities of the built-in `admin` role, and defines the `customrole`.
+
+Please note that for the below code to work you need to create the `customrole` beforehand, you can do that in your [Stream Dashboard](https://dashboard.getstream.io/).
+
 <Tabs groupId="examples">
 <TabItem value="js" label="JavaScript">
 
@@ -20,10 +30,20 @@ client.video.createCallType({
       VideoOwnCapability.SEND_VIDEO,
       VideoOwnCapability.MUTE_USERS,
     ],
-    user: [VideoOwnCapability.SEND_AUDIO, VideoOwnCapability.SEND_VIDEO],
+    ['customrole']: [
+      VideoOwnCapability.SEND_AUDIO,
+      VideoOwnCapability.SEND_VIDEO,
+    ],
+  },
+});
+
+// or edit a built-in call type
+client.video.updateCallType('default', {
+  grants: {
+    /* ... */
   },
 });
 ```
 
 </TabItem>
-</Tabs>
+</Tabs>

docusaurus/video/docusaurus/docs/api/moderation/permissions.mdx

@@ -4,3 +4,29 @@ sidebar_position: 1
 slug: /moderation/permissions
 title: Permissions
 ---
+
+Stream has a role-based permission system. Each user has an application level role, and also channel (chat product) and call (video product) level roles.
+
+Every role (be it application or call/channel level) contains a list of capabilities. A capability is an action (for example create call). The list of capabilities assigned to a role defines what a user is allowed to do.
+
+This page focuses on call-level roles.
+
+## Video capabilities
+
+The list of [video capabilities](../../call_types/builtin/#default-call-capabilities) are available on the Call Types page.
+
+## Call roles
+
+Every user that has access to a call has a call-level role assigned to them. Users can have different roles for different calls (for example a user can be a host in one call, and a viewer in another).
+
+### Built-in roles
+
+Call roles are defined on the call type level. Every [built-in call type](../../call_types/builtin/) comes with a default set of roles set up to match their use-case (a livestreaming app requeires different roles than an audio room). You can customize these roles, for a code example see the [call types settings page](../../call_types/permissions).
+
+It's also possible to customize the roles in your [Stream Dashboard](https://dashboard.getstream.io/).
+
+### Custom roles
+
+It's also possible to define your own custom roles to extend the built-in call types, or when [creating your own call types](../../call_types/manage). For a code example see the [call types settings page](../../call_types/permissions).
+
+You can also create your own roles in your [Stream Dashboard](https://dashboard.getstream.io/).