Permissions

Introduction

This page shows how you can create or update roles for a call type.

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 permissions. A permissions is an action (for example, create a call). The list of permissions assigned to a role defines what a user is allowed to do. Call roles are defined on the call type level.

Configuring roles

When you create a call type, you can specify your role configurations. A role configuration consists of a role name and the list of permissions that are enabled for that role.

When you create a call type, it comes with a default set of configurations. You can override or extend that.

The following example overrides the permissions 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.

client.video.createCallType({
  name: "<call type name>",
  grants: {
    admin: ["send-audio", "send-video", "mute-users"],
    ["customrole"]: ["send-audio", "send-video"],
  },
});

// or edit a built-in call type
client.video.updateCallType({
  name: "default",
  grants: {
    /* ... */
  },
});

client.video.create_call_type(
  name= '<call type name>',
  grants={
    "admin": ["send-audio", "send-video", "mute-users"],
    "customrole": ["send-audio", "send-video"],
  },
)

client.video.update_call_type(name = 'default',
  grants= {
    /* ... */
  },
)

client.Video().CreateCallType(ctx, &getstream.CreateCallTypeRequest{
  Name: "allhands",
  Grants: &map[string][]string{
    "admin": {
      "send-audio", "send-video", "mute-users"
    },
    "customrole": {
      "send-audio", "send-video",
    },
  },
})

client.Video().UpdateCallType(ctx, "default", &getstream.UpdateCallTypeRequest{
  Grants: &map[string][]string{
    /* ... */
  },
})

client.video().createCallType(
  CreateCallTypeRequest.builder()
    .name("allhands")
    .grants(
      Map.of(
        "admin", List.of("send-audio", "send-video", "mute-users"),
        "customrole", List.of("send-audio", "send-video")
      )
    )
    .build()
).execute();

client.video().updateCallType(
  "default",
  UpdateCallTypeRequest.builder()
    .grants(
      Map.of(
        /* ... */
      )
    )
    .build()
).execute();

curl -X POST "https://video.stream-io-api.com/api/v2/video/calltypes?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<call type name>",
    "settings": {
      "audio": { "mic_default_on": true, "default_device": "speaker" }
    },
    "grants": {
      "admin": ["send-audio", "send-video", "mute-users"],
      "customrole": ["send-audio", "send-video"]
    }
  }'

# or edit a built-in call type
curl -X PUT "https://video.stream-io-api.com/api/v2/video/calltypes/default?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": {...}
  }'

See how you can list permissions below.

Built-in roles

There are 5 pre-defined call roles, these are:

user
moderator
host
admin
call-member

You can access the default roles and their permissions in your Stream Dashboard.

You can also list roles and their permissions using the Stream API:

client.video.listCallTypes();

//or
client.video.getCallType({ name: "livestream" });

client.video.list_call_types()

# or
client.video.get_call_type(name= 'livestream')

client.Video().ListCallTypes(ctx, &getstream.ListCallTypesRequest{})

// or
client.Video().GetCallType(ctx, "livestream", &getstream.GetCallTypeRequest{})

curl -X GET "https://video.stream-io-api.com/api/v2/video/calltypes?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt"

# or
curl -X GET "https://video.stream-io-api.com/api/v2/video/calltypes/${CALL_TYPE_NAME}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt"

Permissions

The list of call permissions that you can include in your role configurations:

const resonse = await client.listPermissions();
console.log(response.permissions);

response = client.list_permissions()
print(response.permissions)

request := &getstream.ListPermissionsRequest{}
response, err := client.ListPermissions(ctx, request)
fmt.Printf("Permissions: %+v\n", response)

var request = client.listPermissions();
var response = request.execute();

System.out.println("Permission IDs:");
response.getData().getPermissions().forEach(permission -> {
  System.out.println("- " + permission.getId());
});

curl -X GET "https://video.stream-io-api.com/api/v2/permissions?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json"

Capabilities

When users access calls they’ll receive an own_capabilities field in the call object, which contains all call related capabilities a user is allowed to do. This can be used by client-side SDKs to do permission checks for hiding/showing UI elements (for code examples checkout SDK documentations). Capabilities are not the same as permissions. Permissions are the list of actions the Stream API supports. Capabilities are the list of actions a given user is allowed to do in the scope of a given call taking into account:

application-level and call-level role of the user
call type settings
call-level settings

Geofencing

Settings