Permissions and roles

Every Stream product ships with the same configurable permission system, which allows high resolution control over what users are permitted to do. Each product defines its own resources, actions and grant scopes on top of this shared model.

Getting Started

There are multiple important terms to understand when it comes to permission management. Each permission check comes down to three things:

• Subject - an actor which attempts to perform a certain Action. It can be represented by a User, or by the user's relationship with a resource, such as a ChannelMember in Chat or a FeedMember or Follower in Feeds

• Resource - the item that the Subject attempts to perform an Action on. Chat resources include Channels, Messages and Attachments; Feeds resources include Feeds and Activities; a User can be a Resource in every product

• Action - the exact action that is being performed. For example CreateChannel, AddActivity, DeleteMessage

The purpose of the permission system is to answer the question: is Subject A allowed to perform Action B on Resource C?

Stream provides several concepts which help to control which actions are available to whom:

• Permission - an object which represents actions a subject is allowed to perform

• Role - assigned to a User, or to a user's relationship with a resource, and used to check their permissions

• Grants - the way permissions are assigned to roles, applicable across the entire application or scoped to a product resource such as a channel type in Chat or a feed visibility in Feeds

Permission checking only happens on client-side calls. Server-side calls allow everything so long as a valid API key and secret are provided.

Role Management

To make it easy to get started, all Stream applications come with several roles already built in with permissions that represent the most common use cases. These roles can be customized if needed, and new roles can be created specific to your application.

Assigning a role to a user is what makes them Subject A in the permissions question. Users have one role which grants them permissions for the entire application. Products add a resource-level role on top: Chat assigns channel roles to channel members, and Feeds assigns roles to feed members and followers.

By default all users have the built-in role user assigned. To change a user's role, update the user:

await client.updateUsersPartial({
  users: [
    {
      id: "james_bond",
      set: { role: "special_agent" },
    },
  ],
});

from getstream.models import UpdateUserPartialRequest

response = client.update_users_partial(users=[
    UpdateUserPartialRequest(id="james_bond", set={"role": "special_agent"})
])

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.update_users_partial(Models::UpdateUsersPartialRequest.new(
  users: [Models::UpdateUserPartialRequest.new(
    id: 'james_bond',
    set: { role: 'special_agent' }
  )]
))

$client->updateUsersPartial(new Models\UpdateUsersPartialRequest(
    users: [new Models\UpdateUserPartialRequest(
        id: "james_bond",
        set: (object)["role" => "special_agent"],
    )],
));

resp, err := client.UpdateUsersPartial(ctx, &getstream.UpdateUsersPartialRequest{
  Users: []getstream.UpdateUserPartialRequest{
    {
      ID: "james_bond",
      Set: map[string]any{
        "role": "special_agent",
      },
    },
  },
})

await client.UpdateUsersPartialAsync(new UpdateUsersPartialRequest
{
    Users = new List<UpdateUserPartialRequest>
    {
        new UpdateUserPartialRequest
        {
            Id = "user-id",
            Set = new Dictionary<string, object> { { "role", "special_agent" } },
        },
    },
});

var reqObj = UpdateUserPartialRequest.builder()
    .id("james_bond")
    .set(Map.of("role", "special_agent"))
    .build();
client.updateUsersPartial(UpdateUsersPartialRequest.builder()
    .users(List.of(reqObj))
    .build()).execute();

Assigning and updating resource-level roles is documented with each product:

• Chat channel roles
• Feeds member and follower roles

Subject

Subject can be represented by a User or by the user's relationship with a resource: a ChannelMember in Chat, a FeedMember or Follower in Feeds. Both the user-level role and the resource-level role are taken into account when checking permissions.

Built-in roles

These built-in user-level roles exist in every Stream application:

Each product adds its own resource-level built-in roles, such as channel_member and channel_moderator in Chat or feed_member and feed_follower in Feeds.

Ownership

Some Stream entities have an owner, and ownership can be considered when configuring access permissions. The authenticated user owns itself in every product. Each product defines ownership for its own entities: a Channel or Message is owned by its creator in Chat, and a Feed or Activity is owned by its creator in Feeds.

Using the ownership concept, permissions can be set up so that entity owners are allowed to perform certain actions. For example:

• Update Own User - allows users to change their own properties (except role and team)

• Update Own Message - allows message senders to edit their messages in Chat

• Update Own Activity - allows activity authors to edit their activities in Feeds

Custom Roles

In more sophisticated scenarios custom roles can be used. A Stream application can have up to 25 custom roles. Roles are simple and require only a name to be created. They do nothing until permissions are assigned to the role. To create a new custom role you can use the CreateRole API endpoint:

await client.createRole({
  name: "special_agent",
});

client.create_role("special_agent")

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.create_role(Models::CreateRoleRequest.new(name: 'special_agent'))

$client->createRole(new Models\CreateRoleRequest(name: "special_agent"));

client.CreateRole(ctx, &getstream.CreateRoleRequest{Name: "special_agent"})

await client.CreateRoleAsync(new CreateRoleRequest { Name = "special_agent" });

client.createRole(CreateRoleRequest.builder().name("special_agent").build()).execute();

To delete a previously created role you can use the DeleteRole API endpoint:

await client.deleteRole({
  name: "agent_006",
});

client.delete_role("agent_006")

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.delete_role('agent_006')

$client->deleteRole("agent_006");

client.DeleteRole(ctx, "agent_006", &getstream.DeleteRoleRequest{})

await client.DeleteRoleAsync("special_agent");

client.deleteRole("agent_006", DeleteRoleRequest.builder().build()).execute();

Once you have created a role you can start granting permissions to it. You can also grant or remove permissions for built-in roles.

Granting permissions

Grants attach permissions to roles within a scope. The .app scope exists in every product and applies to operations that occur outside product resources, such as modifying other users or using moderation features. Each product adds its own resource scopes: Chat grants permissions per channel type or per channel, Feeds per feed visibility, and Video per call type.

To list all available permissions you can use the ListPermissions API endpoint:

const { permissions } = await client.listPermissions(); // List of Permission objects

response = client.list_permissions()

require 'getstream_ruby'
Models = GetStream::Generated::Models

response = client.common.list_permissions

$response = $client->listPermissions();

resp, err := client.ListPermissions(ctx, &getstream.ListPermissionsRequest{})

var response = await client.ListPermissionsAsync();

var response = client.listPermissions(ListPermissionsRequest.builder().build()).execute();

Each permission object contains these fields:

You can manage .app scope grants using the app settings update endpoint:

await client.updateAppSettings({
  grants: {
    anonymous: [],
    guest: [],
    user: ["search-user", "mute-user"],
    admin: ["search-user", "mute-user", "ban-user"],
  },
});

client.update_app_settings(grants={
    "anonymous": [],
    "guest": [],
    "user": ["search-user", "mute-user"],
    "admin": ["search-user", "mute-user", "ban-user"],
})

client.update_app_settings(
  grants: {
    'anonymous' => [],
    'guest' => [],
    'user' => ['search-user', 'mute-user'],
    'admin' => ['search-user', 'mute-user', 'ban-user'],
  }
)

$client->updateAppSettings([
    'grants' => [
        'anonymous' => [],
        'guest' => [],
        'user' => ['search-user', 'mute-user'],
        'admin' => ['search-user', 'mute-user', 'ban-user'],
    ],
]);

_, err = client.UpdateAppSettings(ctx, &getstream.AppSettingsRequest{
	Grants: map[string][]string{
		"anonymous": {},
		"guest":     {},
		"user":      {"search-user"},
		"admin":     {"search-user", "ban-user"},
	},
})

await _client.UpdateAppSettingsAsync(new UpdateAppSettingsRequest
{
    Grants = new Dictionary<string, List<string>>
    {
        { "anonymous", new List<string>() },
        { "guest", new List<string>() },
        { "user", new List<string> { "search-user", "mute-user" } },
        { "admin", new List<string> { "search-user", "mute-user", "ban-user" } },
    }
});

var request = UpdateAppSettingsRequest.builder()
    .grants(Map.of(
        "anonymous", List.of(),
        "guest", List.of(),
        "user", List.of("search-user", "mute-user"),
        "admin", List.of("search-user", "mute-user", "ban-user")
    ))
    .build();
client.updateAppSettings(request).execute();

A grants update only changes the roles mentioned in the request. Providing an empty array ([]) as a role's permission list removes all grants for that role, and providing null for the grants field resets the whole scope to default settings. The same semantics apply in the product resource scopes.

UI for configuring permissions

Stream Dashboard provides a user interface to edit permission grants under Roles & Permissions.

Client-side permission checks

API responses for product resources include an own_capabilities field with the actions the current user is allowed to perform on that resource, for example add-activity on a feed. You can use this data to show or hide different parts of the UI based on a user's permissions.

Product permission pages

Resource scopes, capability lists and the full permission tables live with each product:

• Chat permission policies and the Chat permissions reference
• Feeds user permissions
• Video call-type permissions