Permissions v1 (legacy)

// To check your permissions version (server side only)
const { app } = await client.getAppSettings();
console.log(app.permission_version);

// To check your permissions version (server side only)
$response = $client->getAppSettings();
var_dump($response['app']['permission_version']); // "v1" or "v2"

# To check your permissions version (server side only)
response = client.get_app_settings()
print(response["app"]["permission_version"]) # "v1" or "v2"

// To check your permissions version (server side only)
var app = App.get().request();
System.out.println(app.getApp().getPermissionVersion()); // "v1" or "v2"

# To check your permissions version (server side only)
response = client.get_app_settings
puts response['app']['permission_version'] # "v1" or "v2"

// To check your permissions version (server side only)
conf, _ := c.GetAppConfig(ctx)
fmt.Print(conf.App.PermissionVersion)

// To check your permissions version (server side only)
var result = await appClient.GetAppSettingsAsync();
Console.WriteLine(result.App.PermissionVersion); // enum of PermissionVersion.V1 or PermissionVersion.V2

// This is a server-side only feature, choose any of our server-side SDKs to use it

In this version, permissions are associated to channel types only. There are 5 channel types which come built-in automatically, which also have default permissions - commerce, livestream, gaming, messaging, and team. These permissions can be customized if needed, and additional channel types can be created with their own separate set of permissions too.

Permission Checking

Before we dive into more detail on how permission policies are structured, let’s explain how permission checking works in general.

Permission checking is performed taking into account these parameters:

• API Request : the action the user is performing (e.g. send a message, edit a message, etc.)
• User Role: the role of the user making the request
• Channel Type: the channel type
• Resource : the resource involved in the API call (e.g. a channel, a message, a user, etc.)
• Ownership : whether or not the resource is owned by the user (when applicable)

Every time a user performs an API request the following steps happen:

1. The policies for the channel type are loaded

2. The list of policies is iterated based on priority (highest first)

3. If the policy matches the current request, then the request is either accepted or discarded

4. If there is not match, continue iterating until one policy matches

Here’s what a list of permissions look like:

1. Admin users can perform any action

2. Anonymous users are not allowed

3. Users can modify their own messages

4. Users can create channels

5. Members of a channel can read and send messages

6. Anything not matching the previous list should not be allowed

Let’s now see how this would play out and introduce a couple of users: Tommaso and Thierry. Tommaso is an admin and Thierry a user. Thierry is also a member of the “Sailing” channel.

1. Thierry posts a message on channel “soccer”

2. Tommaso edits a message from Thierry

3. Thierry creates a channel called “founders”

4. An anonymous user opens the “Sailing” channel

Here’s what the outcome of these requests would be:

1. 🙅‍♂️ Only the last policy matches and it denies this action

2. 👌 Tommaso is an admin, 1st policy is a match

3. 👌 Thierry is a user, 4th policy is a match

4. 🙅‍♂️ Anonymous users are discarded

Permission Policy Structure

Now that we have a better idea about how the permission system works, let’s define more precisely the structure of a permission policy.

Example list

Let’s now write the example from before into a list of real policies.

import { AnyResource, AnyRole, Allow, Deny } from "stream-chat";

const permissions = [
  new Permission(
    "Admin users can perform any action",
    600,
    AnyResource,
    ["admin"],
    false,
    Allow,
  ),
  new Permission(
    "Anonymous users are not allowed",
    500,
    AnyResource,
    ["anonymous"],
    false,
    Deny,
  ),
  new Permission(
    "Users can modify their own messages",
    400,
    ["UpdateMessage"],
    ["user"],
    true,
    Allow,
  ),
  new Permission(
    "Users can create channels",
    300,
    ["CreateChannel"],
    ["user"],
    false,
    Allow,
  ),
  new Permission(
    "Channel Members",
    200,
    ["ReadChannel", "CreateMessage"],
    ["channel_member"],
    false,
    Allow,
  ),
  new Permission("Discard all", 100, AnyResource, AnyRole, false, Deny),
];

await client.updateChannelType("messaging", { permissions });

[
  {
    "action": "Allow",
    "name": "Admin users can perform any action",
    "resources": ["*"],
    "roles": ["*"],
    "owner": false,
    "priority": 600
  },
  {
    "action": "Deny",
    "name": "Anonymous users are not allowed",
    "resources": ["*"],
    "roles": ["anonymous"],
    "owner": false,
    "priority": 500
  },
  {
    "action": "Allow",
    "name": "Users can modify their own messages",
    "resources": ["*"],
    "roles": ["user"],
    "owner": true,
    "priority": 400
  },
  {
    "action": "Allow",
    "name": "Users can create channels",
    "resources": ["*"],
    "roles": ["user"],
    "owner": false,
    "priority": 300
  },
  {
    "action": "Allow",
    "name": "Channel Members",
    "resources": ["ReadChannel", "CreateMessage"],
    "roles": ["channel_member"],
    "owner": false,
    "priority": 200
  },
  {
    "action": "Deny",
    "name": "Discard all",
    "resources": ["*"],
    "roles": ["*"],
    "owner": false,
    "priority": 100
  }
]

resp, err = client.UpdateChannelType(ctx,
	"messaging",
	map[string]interface{}{
		"permissions": []map[string]interface{}{
			{
				"name":   "Admin users can perform any action",
				"priority": 999,
				"resources": []string{"*"},
				"roles":   []string{"admin"},
				"action":  "Allow",
			},
			{
				"name":   "Channel Members",
				"priority": 200,
				"resources": []string{"ReadChannel", "CreateMessage"},
				"roles":   []string{"channel_member"},
				"action":  "Allow",
			},
		},
	},
)

await channelTypeClient.UpdateChannelTypeAsync("messaging", new ChannelTypeWithStringCommandsRequest
{
  Permissions = new List<ChannelTypePermission>
  {
    new ChannelTypePermission
    {
      Name = "Admin users can perform any action",
      Priority = 999,
      Resources = new List<string> { "*" },
      Roles = new List<string>{"admin"},
      Action = "Allow"
    },
    new ChannelTypePermission
    {
      Name = "Channel Members",
      Priority = 200,
      Resources = new List<string> { "ReadChannel", "CreateMessage" },
      Roles = new List<string>{"channel_member"},
      Action = "Allow"
    }
  },
});

client.update_channel_type("messaging", permissions=[
 {
  "action":"Allow",
  "name": "Admin users can perform any action",
  "resources":["*"],
  "roles": ["*"],
  "priority": 999,
 },
 {
  "action":"Allow",
  "name": "Channel Members",
  "resources":["ReadChannel", "CreateMessage"],
  "roles": ["channel_member"],
  "priority": 200,
 }
])

client.updateChannelType("messaging", [
 [
  "action" => "Allow",
  "name" => "Admin users can perform any action",
  "resources" => ["*"],
  "roles" => ["*"],
  "priority" => 999
 ],
 [
  "action" => "Allow",
  "name" => "Channel Members",
  "resources" => ["ReadChannel", "CreateMessage"],
  "roles" => ["channel_member"],
  "priority" => 200
 ]
])

client.update_channel_type('messaging', permissions: [
  {
   action: 'Allow',
   name: 'Admin users can perform any action',
   resources: ['*'],
   roles: ['*'],
   priority: 999
  },
  {
   action: 'Allow',
   name: 'Channel Members',
   resources: %w[ReadChannel CreateMessage],
   roles: ['channel_member'],
   priority: 200
  }
])

List<PermissionRequestObject> permissions =
  ChannelType.get("messaging").request().getPermissions().stream()
    .map(policy -> PermissionRequestObject.buildFrom(policy))
    .collect(Collectors.toList());

permissions.add(
  PermissionRequestObject.builder()
    .name("Admin users can perform any action")
    .priority(999)
    .resources(Arrays.asList(Resource.ALL))
    .roles(Arrays.asList("*"))
    .action(Action.ALLOW)
    .build());

permissions.add(
  PermissionRequestObject.builder()
    .name("Channel Members")
    .priority(200)
    .resources(Arrays.asList("ReadChannel", "CreateMessage"))
    .roles(Arrays.asList("channel_member"))
    .action(Action.ALLOW)
    .build());

ChannelType.update("messaging").permissions(permissions).request();

// This is a server-side only feature, choose any of our server-side SDKs to use it

User Roles

User Roles are how permissions are grouped together and assigned to a user. Each user role can have separate permissions for different channel types. For example, a moderator for a livestream channel could have different permissions from a moderator for a messaging channel.

Stream maintains a user role for each user_id at an Application level and a Channel level. This is to allow flexibility and to cover a wider range of use cases.

Application User Roles

This is the role assigned to users which applies across the entire application, and gives permissions for things which are outside of a channel’s context, for example, being able to create channels, or search for users.

Channel User Roles

This is the role assigned to a user once they are added to a channel. This role is unique to that channel and a user could have a different role in each channel which they are a member

Change a User Role

const update = await serverClient.updateUser({
  id: "tommaso",
  name: "Tommy Doe",
  role: "admin",
});

client.update_user({
  "id" => "tommaso",
  "name" => "Tommy Doe",
  "role" => "admin",
});

client.update_user({
  "id": "tommaso",
  "name": "Tommy Doe",
  "role": "admin",
});

$response = $client->updateUser([
  'id' => 'tommaso',
  'name' => 'Tommy Doe',
  'role' => 'admin'
]);

User
 .upsert()
 .user(
  UserRequestObject.builder().id("tommaso").name("Tommy Doe").role("admin").build())
 .request();

user := User{
  ID: "tommaso",
  Role: "admin",
  ExtraData: map[string]interface{}{
    "name": "Tommy Doe",
  }
};

client.UpdateUser(&user);

var user = new UserRequest
{
  Id = "tommaso",
  Name = "Tommy Doe",
  Role = Role.Admin,
};
await userClient.UpsertAsync(user);

// This is a server-side only feature, choose any of our server-side SDKs to use it

Add Moderators to a Channel

const channel = serverClient.channel("livestream", "fortnite");
await channel.addModerators(["thierry", "tommaso"]));

channel = client.channel("livestream", "fortnite");
channel.add_moderators(["thierry", "tommaso"]);

channel = client.channel("livestream", "fortnite");
channel.add_moderators(["thierry", "tommaso"]);

$channel = $client->Channel("livestream", "fortnite");
$channel->create('thierry');

$response = $channel->addModerators(['thierry', 'jenny']);

Channel.update(
    "livestream",
    "fortnite")
  .addModerators(Arrays.asList("thierry", "tommaso"))
  .request());

channel = client.Channel("livestream", "fortnite");
channel.AddModerators("thierry", "tommaso");

await channelClient.AddModeratorsAsync("livestream", "fortnite", new[] { "thierry", "tommaso" });

// This is a server-side only feature, choose any of our server-side SDKs to use it

Remove Moderators From a Channel

await channel.demoteModerators(["thierry"]));

channel.demote_moderators(["thierry"]);

channel.demote_moderators(["thierry"]);

$channel->demoteModerators(['thierry']);

Channel.update(
    "livestream",
    "fortnite")
  .demoteModerator("thierry")
  .request());

channel.DemoteModerators("thierry");

await channelClient.DemoteModeratorsAsync("livestream", "fortnite", new[] { "thierry" });

// This is a server-side only feature, choose any of our server-side SDKs to use it

Custom Roles

You can also create custom roles if the built-in roles are not enough to cover all your use cases. This requires an upgrade to Permissions version. Please contact support for help with this upgrade.

Permission Resources

Permissions policies can match one or more resources. Here is the complete list of permissions available. Please keep in mind that this only applies to API calls done by clients, API requests performed from your backend do not need to pass a permission check.

Default Permissions

The five built-in channel types ship with default permission setting.

messaging

livestream

team

commerce

gaming