# 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.

<Admonition type="info">

In the legacy permission system users can never access users or resources from other teams. In [Permissions V2](https://getstream.io/docs/platform/permissions/) it is possible to alter this behavior using multi-tenant permissions.

</Admonition>

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.

<Tabs>

```js label="Node.js"
// shows the current status
const appSettings = await client.getApp();
console.log(appSettings.app.multi_tenant_enabled);

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

```python label="Python"
from getstream import Stream

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

```ruby label="Ruby"
require 'getstream_ruby'
Models = GetStream::Generated::Models

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

```php label="PHP"
$client->updateApp(new Models\UpdateAppRequest(multiTenantEnabled: true));
```

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

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

```csharp label="C#"
await client.UpdateAppAsync(new UpdateAppRequest { MultiTenantEnabled = true });
```

```java label="Java"
client.updateApp(UpdateAppRequest.builder()
    .multiTenantEnabled(true)
    .build()).execute();
```

</Tabs>

<Admonition type="info">

You only need to activate multi-tenancy once per application.

</Admonition>

<Admonition type="warning">

Do not turn off multi-tenancy on an application without very careful consideration, as this will turn off teams checking, which gives users the ability to access resources across all teams. Do not change it on a production app without testing that your integration supports it correctly.

Make sure to activate multi-tenancy before using teams.

</Admonition>

## 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.

<Tabs>

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

```python label="Python"
from getstream.models import UpdateUserPartialRequest

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

```ruby label="Ruby"
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'] }
  )]
))
```

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

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

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

```java label="Java"
// 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();
```

</Tabs>

<Admonition type="info">

A user can be a member of a maximum of 250 teams. Team name is limited to 100 bytes. There is no limit to how many teams your application can have.

</Admonition>

<Admonition type="warning">

User teams are included in all User object payloads. We recommend to have short team names to reduce response payload sizes

</Admonition>

<Admonition type="warning">

In Permissions v1, user teams can only be changed using server-side auth. This ensures users can't change their own team membership. In Permissions v2 it is possible to update user teams from client-side if `UpdateUserTeam` action is granted to the user

</Admonition>

## 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](https://getstream.io/chat/docs/node/multi-tenant-chat/) and [multi-tenant video](https://getstream.io/video/docs/api/multi-tenant/).

## 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.

<Tabs>

```js label="Node.js"
// 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,
    },
  },
});
```

```python label="Python"
# 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,
        }
    )
)
```

```ruby label="Ruby"
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' } }
  )
)
```

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

```go label="Go"
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,
    },
  },
})
```

```csharp label="C#"
// 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" } } },
    },
});
```

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

</Tabs>

<Admonition type="info">

Users that cannot be displayed to the current user due to lack of permissions will be omitted from response.

</Admonition>

## 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](https://getstream.io/chat/docs/node/multi-tenant-chat/#query-channels) and [querying calls](https://getstream.io/video/docs/api/multi-tenant/#query-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:

<Tabs>

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

```python label="Python"
from getstream.models import UserRequest

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

```ruby label="Ruby"
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' } }
    )
  }
))
```

```php label="PHP"
$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"],
        ],
    )],
));
```

```go label="Go"
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",
        },
      },
    },
  },
})
```

```csharp label="C#"
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" },
                },
            }
        },
    },
});
```

```java label="Java"
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();
```

</Tabs>

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](https://getstream.io/chat/docs/node/multi-tenant-chat/#multi-tenant-permissions). Granting them works like any other permission; see [permissions and roles](https://getstream.io/docs/platform/permissions/).

## 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](https://getstream.io/chat/docs/node/multi-tenant-chat/#team-usage-statistics) on the chat multi-tenancy page.


---

This page was last updated at 2026-08-07T13:10:45.328Z.

For the most recent version of this documentation, visit [https://getstream.io/docs/platform/multi-tenancy/](https://getstream.io/docs/platform/multi-tenancy/).