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 capabilities. A capability is an action (for example, create a call). The list of capabilities 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 capabilities 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 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.

client.video.createCallType({
  name: "<call type name>",
  grants: {
    admin: [
      VideoOwnCapability.SEND_AUDIO,
      VideoOwnCapability.SEND_VIDEO,
      VideoOwnCapability.MUTE_USERS,
    ],
    ["customrole"]: [
      VideoOwnCapability.SEND_AUDIO,
      VideoOwnCapability.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": [
      OwnCapability.SEND_AUDIO.to_str(),
      OwnCapability.SEND_VIDEO.to_str(),
      OwnCapability.MUTE_USERS.to_str(),
    ],
    "customrole": [
      OwnCapability.SEND_AUDIO.to_str(),
      OwnCapability.SEND_VIDEO.to_str(),
    ],
  },
)

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

client.Video().CreateCallType(ctx, &getstream.CreateCallTypeRequest{
  Name: "allhands",
  Grants: &map[string][]string{
    "admin": {
      SEND_AUDIO.String(),
      SEND_VIDEO.String(),
      MUTE_USERS.String(),
    },
    "customrole": {
      SEND_AUDIO.String(),
      SEND_VIDEO.String(),
    },
  },
})

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

client.video().createCallType(
  CreateCallTypeRequest.builder()
    .name("allhands")
    .grants(
      Map.of(
        "admin", List.of(OwnCapability.SEND_AUDIO.toString(), OwnCapability.SEND_VIDEO.toString(), OwnCapability.MUTE_USERS.toString()),
        "customrole", List.of(OwnCapability.SEND_AUDIO.toString(), OwnCapability.SEND_VIDEO.toString())
      )
    )
    .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": {...}
  }'

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 capabilities in your Stream Dashboard.

Capabilities

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

• join-call
• read-call
• create-call
• join-ended-call
• join-backstage
• update-call
• update-call-settings
• screenshare
• send-video
• send-audio
• start-record-call
• stop-record-call
• start-broadcast-call
• stop-broadcast-call
• end-call
• mute-users
• update-call-permissions
• block-users
• create-reaction
• pin-for-everyone
• remove-call-member
• start-transcription-call
• stop-transcription-call