Multi-tenancy and teams

Many apps built on Stream have customers of their own. If you're building something like Slack, or a SaaS application like InVision, you want to make sure that one customer can't read another customer's data. Stream can be configured in multi-tenant mode so that users are organized in separated teams that cannot interact with each other.

Teams

Stream has the concept of teams for users and the resources they create, such as channels and calls. The purpose of teams is to provide a simple way to separate different groups of users within a single application.

If a user belongs to a team, the API will ensure that such user will only be able to connect to resources from the same team. Features such as user search are limited so that a user can only search for users from the same team by default.

When enabling multi-tenant mode all user requests will always ensure that the request applies to a team the user belongs to. For instance, if a user from team "blue" tries to delete a message that was created on a channel from team "red" the API will return an error. If a user doesn't have a team set, it will only have access to users and resources that don't have a team.

Enable Teams for your application

In order to use Teams, your application must have multi-tenant mode enabled. You can enable multi-tenant from the dashboard (Overview screen) or by calling the Application Settings endpoint.

// shows the current status
const appSettings = await client.getApp();
console.log(appSettings.app.multi_tenant_enabled);

// enables teams
client.updateApp({
  multi_tenant_enabled: true,
});

from getstream import Stream

client = Stream(api_key="{{ api_key }}", api_secret="{{ api_secret }}")
client.update_app(multi_tenant_enabled=True)

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

client.common.update_app(Models::UpdateAppRequest.new(multi_tenant_enabled: true))

$client->updateApp(new Models\UpdateAppRequest(multiTenantEnabled: true));

res, _ := client.GetApp(ctx, &getstream.GetAppRequest{})
fmt.Println(res.Data.App.MultiTenantEnabled)

// enables teams
client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  MultiTenantEnabled: getstream.PtrTo(true),
})

await client.UpdateAppAsync(new UpdateAppRequest { MultiTenantEnabled = true });

client.updateApp(UpdateAppRequest.builder()
    .multiTenantEnabled(true)
    .build()).execute();

User teams

When using teams, users must be created from your back-end and specify which teams they are a member of. This is necessary to ensure that a user cannot pick its own team.

client.upsertUsers([
  {
    id: "<user id>",
    name: "Sara",
    teams: ["red", "blue"],
  },
]);

from getstream.models import UpdateUserPartialRequest

client.update_users_partial(users=[
    UpdateUserPartialRequest(id=user_id, set={"teams": ["red", "blue"]})
])

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

client.common.update_users_partial(Models::UpdateUsersPartialRequest.new(
  users: [Models::UpdateUserPartialRequest.new(
    id: user_id,
    set: { 'teams' => ['red', 'blue'] }
  )]
))

$client->updateUsersPartial(new Models\UpdateUsersPartialRequest(
    users: [new Models\UpdateUserPartialRequest(
        id: $userId,
        set: (object)["teams" => ["red", "blue"]],
    )],
));

resp, err := client.UpdateUsersPartial(ctx, &getstream.UpdateUsersPartialRequest{
  Users: []getstream.UpdateUserPartialRequest{
    {
      ID: user.ID,
      Set: map[string]any{
        "teams": []string{"red", "blue"},
      },
    },
  },
})

await client.UpdateUsersPartialAsync(new UpdateUsersPartialRequest
{
    Users = new List<UpdateUserPartialRequest>
    {
        new UpdateUserPartialRequest
        {
            ID = user.ID,
            Set = new Dictionary<string, object> { { "teams", new[] { "red", "blue" } } },
        },
    },
});

// Partial updating a user to be part of red and blue team
client.updateUsersPartial(UpdateUsersPartialRequest.builder()
    .users(List.of(UpdateUserPartialRequest.builder()
        .id(user.getId())
        .set(Map.of("teams", List.of("red", "blue")))
        .build()))
    .build()).execute();

Team resources

Channels and calls can be associated with a team. Users can create them client-side, but if their user is part of a team, they will have to specify a team or the request will be rejected with an error.

Setting a team on a channel or call ensures proper permission checking for a multi-tenant application. Keep in mind that you will still need to enforce that channel and call IDs are unique. Two common approaches: generate random UUIDs, or include the team name as a prefix to avoid collisions (ie. "red-general" and "blue-general" instead of just "general").

For creation examples per product, see multi-tenant chat and multi-tenant video.

User search

By default the user search will only return results from teams that the user is a part of. The API injects filter {teams: {$in: ["red", "blue"]}} for every request that doesn't already contain a filter for the teams field. If you want to query users from all teams, you have to provide an empty filter like this: {teams:{}}.

For server-side requests, this filter does not apply and you can search as usual and also filter by teams.

// search for users by name and team
client.queryUsers({
  payload: {
    filter_conditions: {
      name: "Nick",
      teams: { $in: ["red", "blue"] },
    },
  },
});

// search for users that are not part of any team
client.queryUsers({
  payload: {
    filter_conditions: {
      name: "Tom",
      teams: null,
    },
  },
});

# search for users by name and team
response = client.query_users(
    QueryUsersPayload(
        filter_conditions={
            "name": {"$eq": "Nick"},
            "teams": {"$in": ["red", "blue"]},
        }
    )
)

# search for users that are not part of any team
response = client.query_users(
    QueryUsersPayload(
        filter_conditions={
            "teams": None,
        }
    )
)

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

# Server side usage, it searches all teams implicitly
client.common.query_users(
  Models::QueryUsersPayload.new(
    filter_conditions: { 'name' => { '$eq' => 'Nick' } }
  )
)

// Server side usage, it searches all teams implicitly
$response = $client->queryUsers(new Models\QueryUsersPayload(
    filterConditions: (object)["name" => (object)['$eq' => "Nick"]],
));

response, err := client.QueryUsers(ctx, &getstream.QueryUsersRequest{
  Payload: &getstream.QueryUsersPayload{
    FilterConditions: map[string]interface{}{
      "name":  "Nick",
      "teams": map[string]interface{}{"$in": []string{"red", "blue"}},
    },
  },
})

// search for users that are not part of any team
response, err = client.QueryUsers(ctx, &getstream.QueryUsersRequest{
  Payload: &getstream.QueryUsersPayload{
    FilterConditions: map[string]interface{}{
      "teams": nil,
    },
  },
})

// Server side usage, it searches all teams implicitly
await client.QueryUsersAsync(new QueryUsersPayload
{
    FilterConditions = new Dictionary<string, object>
    {
        { "name", new Dictionary<string, string> { { "$eq", "Nick" } } },
    },
});

client.queryUsers(
  QueryUsersRequest.builder()
    .Payload(
      QueryUsersPayload.builder()
        .filterConditions(
          Map.of("name", "Nick", "teams", Map.of("$in", List.of("red", "blue"))
        )
        .build()
    )
    .build()
).execute();

Querying team resources

Query endpoints follow the same rule. When using multi-tenant, client-side queries will only return channels or calls that match the query and are on the same team as the user. The API injects filter {team: {$in: [<user_teams>]}} for every request that doesn't already contain a filter for the team field. If you want to query across all teams, you have to provide an empty filter like this: {team:{}}. For server-side requests, this filter does not apply.

For the product query endpoints, see querying channels and querying calls.

Team based roles

By default a user will be assigned only 1 role (ie. user, admin, etc.). If you would like to have different roles depending on the team the user is part of, you can do so by specifying a separate role per team. This team based role is applicable only on resources that belong to that team. Let's imagine user Jane, she's a user with role user throughout the application, however on team red we would like to give her elevated permissions and give her the admin role. We can do this by updating the user as follows:

await client.upsertUser({
  id: "Jane",
  role: "user",
  teams: ["red", "blue"],
  teams_role: {
    red: "admin",
    blue: "user",
  },
});

from getstream.models import UserRequest

response = client.upsert_users(
    UserRequest(
        id="Jane",
        role="user",
        teams=["red", "blue"],
        teams_role={
            "red": "admin",
            "blue": "user",
        },
    )
)

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

response = client.common.update_users(Models::UpdateUsersRequest.new(
  users: {
    'Jane' => Models::UserRequest.new(
      id: 'Jane',
      role: 'user',
      teams: ['red', 'blue'],
      custom: { 'teams_role' => { 'red' => 'admin', 'blue' => 'user' } }
    )
  }
))

$client->updateUsers(new Models\UpdateUsersRequest(
    users: ["Jane" => new Models\UserRequest(
        id: "Jane",
        role: "user",
        teams: ["red", "blue"],
        custom: (object)[
            "teams_role" => (object)["red" => "admin", "blue" => "user"],
        ],
    )],
));

response, err := client.UpdateUsers(ctx, &getstream.UpdateUsersRequest{
  Users: map[string]getstream.UserRequest{
    "Jane": {
      ID:    "Jane",
      Role:  getstream.PtrTo("user"),
      Teams: []string{"red", "blue"},
      Custom: map[string]any{
        "teams_role": map[string]string{
          "red":  "admin",
          "blue": "user",
        },
      },
    },
  },
})

await client.UpdateUsersAsync(new UpdateUsersRequest
{
    Users = new Dictionary<string, UserRequest>
    {
        {
            "Jane", new UserRequest
            {
                ID = "Jane",
                Role = "user",
                Teams = new List<string> { "red", "blue" },
                TeamsRole = new Dictionary<string, string>
                {
                    { "red", "admin" },
                    { "blue", "user" },
                },
            }
        },
    },
});

var response = client.updateUsers(UpdateUsersRequest.builder()
    .users(Map.of("Jane", UserRequest.builder()
        .id("Jane")
        .role("user")
        .teams(List.of("red", "blue"))
        .teamsRole(Map.of("red", "admin", "blue", "user"))
        .build()))
    .build()).execute();

If no team based role is set for a team, the system uses the role of the user. For example, user Janet is a member of teams red, blue and orange. She has role user and team based roles { "red": "admin", "blue": "user" }:

• On team red, she will have admin level permissions. This means that on resources that belong to team red, she will have admin level permissions.
• On resources from team blue, she has user level permissions.
• On resources from team orange, she also has user level permissions (because no team role was assigned for this team).

Please be aware team based roles will only work when multitenancy is enabled.

Multi-tenant permissions

By default, for multi-tenant applications, all objects (users, channels, calls and messages) must belong to the same team to be able to interact. Multi-tenant permissions enable overriding that behavior, so that certain users can have permissions to interact with objects on any team. The built-in global_moderator and global_admin roles are designed for this; their grants use -any-team permission IDs such as create-channel-any-team and search-user-any-team.

The default grants for these roles are listed per scope in each product's reference; see the chat grant tables. Granting them works like any other permission; see permissions and roles.

Team usage statistics

For multi-tenant chat applications, you can query usage statistics broken down by team for billing, monitoring and analytics. See team usage statistics on the chat multi-tenancy page.