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

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

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](https://getstream.io/signin/) (Overview screen) or by calling the Application Settings endpoint.

```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();
```

>
> **Info:** You only need to activate multi-tenancy once per application.
>

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

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

```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();
```

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

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

>
> **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
>

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

### Creating chat channels with a team

```js label="JavaScript"
// Creates the channel red-general for team red
client.channel("messaging", "red-general", { team: "red" }).create();
```

```kotlin label="Kotlin"
// Creates the red-general channel for the red team
client.createChannel(
  channelType = "messaging",
  channelId = "red-general",
  memberIds = listOf("user1", "user2"),
  extraData = mapOf("team" to "red")
).enqueue { result ->
  if (result is Result.Success) {
    val channel = result.value
  } else {
    // Handle Result.Failure
  }
}
```

```java label="Java (Android)"
// Creates the red-general channel for the red team
Map<String, Object> extraData = new HashMap<>();
List<String> memberIds = new LinkedList<>();
extraData.put("team", "red");
client.createChannel("messaging", "red-general", memberIds, extraData).enqueue(result -> {
  if (result.isSuccess()) {
    Channel channel = result.getOrNull();
  } else {
    // Handle error
  }
});
```

```swift label="Swift"
import StreamChat

/// 1: Create a `ChannelId` that represents the channel you want to create.
let channelId = ChannelId(type: .messaging, id: "general")

/// 2: Use the `ChatClient` to create a `ChatChannelController` with the `ChannelId`.
let channelController = try chatClient.channelController(
  createChannelWithId: channelId,
  name: "Channel Name",
  imageURL: nil,
  team: "red"
)

/// 3: Call `ChatChannelController.synchronize` to create the channel.
channelController.synchronize { error in
  if let error = error {
    /// 4: Handle possible errors
    print(error)
  }
}
```

```dart label="Dart"
// Creates the channel red-general for team red
final channel = client.channel(
  'messaging',
  id: 'red-general',
  extraData: {'team': 'red'},
);
await channel.create();
```

```cpp label="Unreal"
const FChannelProperties Properties{
  TEXT("messaging"),   // Type
  TEXT("red-general"),  // Id
  TEXT("red"),      // Team

};
Client->CreateChannel(
  Properties,
  [](UChatChannel* Channel)
  {
    // Channel created
  });
```

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

channel = client.chat.channel("messaging", "red-general")
channel.get_or_create(data=ChannelInput(created_by_id=user_id, team="red"))
```

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

client.chat.get_or_create_channel('messaging', 'red-general', Models::ChannelGetOrCreateRequest.new(
  data: Models::ChannelInput.new(
    team: 'red',
    created_by_id: user_id
  )
))
```

```php label="PHP"
$client->getOrCreateChannel("messaging", "red-general", new Models\ChannelGetOrCreateRequest(
    data: new Models\ChannelInput(
        team: "red",
        createdByID: $userId,
    ),
));
```

```go label="Go"
channel := client.Chat().Channel("messaging", "red-general")
resp, err := channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
  Data: &getstream.ChannelInput{
    CreatedByID: getstream.PtrTo(owner.ID),
    Team:        getstream.PtrTo("red"),
  },
})
```

```csharp label="C#"
await chat.GetOrCreateChannelAsync("messaging", "red-general", new ChannelGetOrCreateRequest
{
    Data = new ChannelInput
    {
        Team = "red",
        CreatedByID = user.ID,
    },
});
```

### Creating video calls with a team

```js label="Node.js"
client.video.call("default", "red-team-weekly").create({
  data: { team: "red", created_by_id: "<user_id>" },
});
```

```py label="Python"
call = client.video.call("default", call_id)

response = call.create(
    data=CallRequest(
        created_by_id=user_id,
        team="blue",
    )
)
```

```go label="Go"
call = client.Video().Call("default", "callID")
response, err := call.GetOrCreate(ctx, &getstream.GetOrCreateCallRequest{
  Data: &getstream.CallRequest{
    Team:        getstream.PtrTo("blue"),
    CreatedByID: getstream.PtrTo("<user_id>"),
  },
})
```

```java label="Java"
var call = new Call("default", "callID", client.video());
call.getOrCreate(
  GetOrCreateCallRequest.builder()
    .data(CallRequest.builder()
      .team("blue")
      .createdByID("<user_id>")
      .build()
    )
    .build()
);
```

```bash label="cURL"
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "created_by_id": "sacha@getstream.io",
      "team": "blue"
    }
  }'
```

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

```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();
```

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

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

### Querying chat channels

```js label="JavaScript"
// query all channels from teams that user is a part of
await client.queryChannels({});

// query all channels from all teams
await client.queryChannels({ team: {} });

// query all channels with no teams
await client.queryChannels({ team: { $eq: null } });
```

```kotlin label="Kotlin"
// query all channels from teams that user is a part of
val filter = Filters.and(
    Filters.eq("type", "messaging"),
    Filters.`in`("members", listOf(userId)),
)

// query all channels from all teams
val filter = Filters.eq("team", emptyMap<Any, Any>())

client.queryChannels(QueryChannelsRequest(filter = filter, limit = 25)).enqueue()
```

```dart label="Dart"
// query all channels from teams that user is a part of
await client.queryChannels(filter: Filter.empty());

// query all channels from all teams
await client.queryChannels(filter: Filter.custom(key: 'team', value: {}));
```

```cpp label="Unreal"
// query all channels from teams that user is a part of
Client->QueryChannels();

// query all channels from all teams
Client->QueryChannels(FFilter::Empty(TEXT("team")));
```

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

# query all channels from teams that user is a part of
client.chat.query_channels(Models::QueryChannelsRequest.new(
  filter_conditions: {}
))

# query all channels from all teams
client.chat.query_channels(Models::QueryChannelsRequest.new(
  filter_conditions: { 'team' => {} }
))
```

```php label="PHP"
// query all channels from teams that user is a part of
$response = $client->queryChannels(new Models\QueryChannelsRequest(
    filterConditions: (object)[],
));

// query all channels from all teams
$response = $client->queryChannels(new Models\QueryChannelsRequest(
    filterConditions: (object)["team" => (object)[]],
));
```

```go label="Go"
resp, err := client.Chat().QueryChannels(ctx, &getstream.QueryChannelsRequest{
  FilterConditions: getstream.PtrTo(map[string]any{}),
})

// query all channels from all teams
resp, err = client.Chat().QueryChannels(ctx, &getstream.QueryChannelsRequest{
  FilterConditions: getstream.PtrTo(map[string]any{
    "team": map[string]string{},
  }),
})
```

```csharp label="C#"
// query all channels from teams that user is a part of
await chat.QueryChannelsAsync(new QueryChannelsRequest
{
    FilterConditions = new Dictionary<string, object>(),
});

// query all channels from all teams
await chat.QueryChannelsAsync(new QueryChannelsRequest
{
    FilterConditions = new Dictionary<string, object>
    {
        { "team", new Dictionary<string, string>() },
    },
});
```

```java label="Java"
// query all channels from teams that user is a part of
chat.queryChannels(QueryChannelsRequest.builder()
    .filterConditions(Map.of())
    .build()).execute();

// query all channels from all teams
chat.queryChannels(QueryChannelsRequest.builder()
    .filterConditions(Map.of("team", Map.of()))
    .build()).execute();
```

>
> **Info:** In case if response contains channels that user cannot access, an access error will be returned.
>

### Querying video calls

```js label="Node.js"
// All calls
client.video.queryCalls();

// Calls without team
client.video.queryCalls({
  filter_conditions: {
    team: null,
  },
});

// Calls with specific team
client.video.queryCalls({
  filter_conditions: {
    team: "blue",
  },
});
```

```py label="Python"
# query calls by team field
response = client.video.query_calls(
    filter_conditions={"id": call_id, "team": {"$eq": "blue"}}
)

# retrieve calls without a team
response = client.video.query_calls(
    filter_conditions={"id": call_id, "team": {"$eq": "blue"}}
)
```

```go label="Go"
response, err := client.Video().QueryCalls(ctx, &getstream.QueryCallsRequest{
  FilterConditions: &map[string]interface{}{
    "id":   call_id,
    "team": map[string]interface{}{"$eq": "blue"},
  },
})

// retrieve calls without a team
response, err := client.Video().QueryCalls(ctx, &getstream.QueryCallsRequest{
  FilterConditions: &map[string]interface{}{
    "id":   call_id,
    "team": &map[string]interface{}{"$eq": nil},
  },
})
```

```java label="Java"
client.video().queryCalls(
  QueryCallsRequest.builder()
    .filterConditions(Map.of(
      "id", callId,
      "team", Map.of("$eq", "blue")
    ))
    .build()
).execute();

// retrieve calls without a team
client.video().queryCalls(
  QueryCallsRequest.builder()
    .filterConditions(Map.of(
      "id", callId,
      "team", Map.of("$eq", null)
    ))
    .build()
).execute();
```

```bash label="cURL"
# All calls
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt"

# Calls without team
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{"filter_conditions": {"team": null}}'

# Calls with a specific team
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{"filter_conditions": {"team": "blue"}}'
```

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

```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();
```

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

Granting them works like any other permission; see [permissions and roles](https://getstream.io/docs/platform/permissions/).

The tables below list the default grants for these roles. The `.app` scope applies across products; the remaining scopes are the built-in chat channel types.

### Scope `.app`

| Permission ID               | global_moderator | global_admin |
| --------------------------- | ---------------- | ------------ |
| flag-user-any-team          | ✅               | ✅           |
| mute-user-any-team          | ✅               | ✅           |
| read-flag-reports-any-team  | ✅               | ✅           |
| search-user-any-team        | ✅               | ✅           |
| update-flag-report-any-team | ✅               | ✅           |
| update-user-owner           | ✅               | ✅           |

### Scope `messaging`

| Permission ID                          | global_moderator | global_admin |
| -------------------------------------- | ---------------- | ------------ |
| add-links-any-team                     | ✅               | ✅           |
| ban-channel-member-any-team            | ✅               | ✅           |
| ban-user-any-team                      | ✅               | ✅           |
| create-call-any-team                   | ✅               | ✅           |
| create-channel-any-team                | ✅               | ✅           |
| create-message-any-team                | ✅               | ✅           |
| create-attachment-any-team             | ✅               | ✅           |
| create-mention-any-team                | ✅               | ✅           |
| create-reaction-any-team               | ✅               | ✅           |
| create-system-message-any-team         | ✅               | ✅           |
| delete-attachment-any-team             | ✅               | ✅           |
| delete-channel-any-team                | ✖️               | ✅           |
| delete-channel-owner-any-team          | ✅               | ✖️           |
| delete-message-any-team                | ✅               | ✅           |
| delete-reaction-any-team               | ✅               | ✅           |
| flag-message-any-team                  | ✅               | ✅           |
| join-call-any-team                     | ✅               | ✅           |
| mute-channel-any-team                  | ✅               | ✅           |
| pin-message-any-team                   | ✅               | ✅           |
| read-channel-any-team                  | ✅               | ✅           |
| read-channel-members-any-team          | ✅               | ✅           |
| read-message-flags-any-team            | ✅               | ✅           |
| recreate-channel-any-team              | ✖️               | ✅           |
| recreate-channel-owner-any-team        | ✅               | ✖️           |
| remove-own-channel-membership-any-team | ✅               | ✅           |
| run-message-action-any-team            | ✅               | ✅           |
| send-custom-event-any-team             | ✅               | ✅           |
| skip-channel-cooldown-any-team         | ✅               | ✅           |
| skip-message-moderation-any-team       | ✅               | ✅           |
| truncate-channel-any-team              | ✖️               | ✅           |
| truncate-channel-owner-any-team        | ✅               | ✖️           |
| unblock-message-any-team               | ✅               | ✅           |
| update-channel-any-team                | ✅               | ✅           |
| update-channel-cooldown-any-team       | ✅               | ✅           |
| update-channel-frozen-any-team         | ✅               | ✅           |
| update-channel-members-any-team        | ✅               | ✅           |
| update-message-any-team                | ✅               | ✅           |
| upload-attachment-any-team             | ✅               | ✅           |

### Scope `livestream`

| Permission ID                          | global_moderator | global_admin |
| -------------------------------------- | ---------------- | ------------ |
| add-links-any-team                     | ✅               | ✅           |
| ban-channel-member-any-team            | ✅               | ✅           |
| ban-user-any-team                      | ✅               | ✅           |
| create-call-any-team                   | ✅               | ✅           |
| create-channel-any-team                | ✅               | ✅           |
| create-message-any-team                | ✅               | ✅           |
| create-attachment-any-team             | ✅               | ✅           |
| create-mention-any-team                | ✅               | ✅           |
| create-reaction-any-team               | ✅               | ✅           |
| create-system-message-any-team         | ✅               | ✅           |
| delete-attachment-any-team             | ✅               | ✅           |
| delete-channel-any-team                | ✖️               | ✅           |
| delete-message-any-team                | ✅               | ✅           |
| delete-reaction-any-team               | ✅               | ✅           |
| flag-message-any-team                  | ✅               | ✅           |
| join-call-any-team                     | ✅               | ✅           |
| mute-channel-any-team                  | ✅               | ✅           |
| pin-message-any-team                   | ✅               | ✅           |
| read-channel-any-team                  | ✅               | ✅           |
| read-channel-members-any-team          | ✅               | ✅           |
| read-message-flags-any-team            | ✅               | ✅           |
| recreate-channel-any-team              | ✖️               | ✅           |
| remove-own-channel-membership-any-team | ✖️               | ✅           |
| run-message-action-any-team            | ✅               | ✅           |
| send-custom-event-any-team             | ✅               | ✅           |
| skip-channel-cooldown-any-team         | ✅               | ✅           |
| skip-message-moderation-any-team       | ✅               | ✅           |
| truncate-channel-any-team              | ✖️               | ✅           |
| unblock-message-any-team               | ✅               | ✅           |
| update-channel-any-team                | ✖️               | ✅           |
| update-channel-cooldown-any-team       | ✅               | ✅           |
| update-channel-frozen-any-team         | ✅               | ✅           |
| update-channel-members-any-team        | ✖️               | ✅           |
| update-message-any-team                | ✅               | ✅           |
| upload-attachment-any-team             | ✅               | ✅           |

### Scope `team`

| Permission ID                          | global_moderator | global_admin |
| -------------------------------------- | ---------------- | ------------ |
| add-links-any-team                     | ✅               | ✅           |
| ban-channel-member-any-team            | ✅               | ✅           |
| ban-user-any-team                      | ✅               | ✅           |
| create-call-any-team                   | ✅               | ✅           |
| create-channel-any-team                | ✅               | ✅           |
| create-message-any-team                | ✅               | ✅           |
| create-attachment-any-team             | ✅               | ✅           |
| create-mention-any-team                | ✅               | ✅           |
| create-reaction-any-team               | ✅               | ✅           |
| create-system-message-any-team         | ✅               | ✅           |
| delete-attachment-any-team             | ✅               | ✅           |
| delete-channel-any-team                | ✖️               | ✅           |
| delete-channel-owner-any-team          | ✅               | ✖️           |
| delete-message-any-team                | ✅               | ✅           |
| delete-reaction-any-team               | ✅               | ✅           |
| flag-message-any-team                  | ✅               | ✅           |
| join-call-any-team                     | ✅               | ✅           |
| mute-channel-any-team                  | ✅               | ✅           |
| pin-message-any-team                   | ✅               | ✅           |
| read-channel-any-team                  | ✅               | ✅           |
| read-channel-members-any-team          | ✅               | ✅           |
| read-message-flags-any-team            | ✅               | ✅           |
| recreate-channel-any-team              | ✖️               | ✅           |
| recreate-channel-owner-any-team        | ✅               | ✖️           |
| remove-own-channel-membership-any-team | ✅               | ✅           |
| run-message-action-any-team            | ✅               | ✅           |
| send-custom-event-any-team             | ✅               | ✅           |
| skip-channel-cooldown-any-team         | ✅               | ✅           |
| skip-message-moderation-any-team       | ✅               | ✅           |
| truncate-channel-any-team              | ✖️               | ✅           |
| truncate-channel-owner-any-team        | ✅               | ✖️           |
| unblock-message-any-team               | ✅               | ✅           |
| update-channel-any-team                | ✅               | ✅           |
| update-channel-cooldown-any-team       | ✅               | ✅           |
| update-channel-frozen-any-team         | ✅               | ✅           |
| update-channel-members-any-team        | ✅               | ✅           |
| update-message-any-team                | ✅               | ✅           |
| upload-attachment-any-team             | ✅               | ✅           |

### Scope `commerce`

| Permission ID                          | global_moderator | global_admin |
| -------------------------------------- | ---------------- | ------------ |
| add-links-any-team                     | ✅               | ✅           |
| ban-channel-member-any-team            | ✅               | ✅           |
| ban-user-any-team                      | ✅               | ✅           |
| create-call-any-team                   | ✅               | ✅           |
| create-channel-any-team                | ✅               | ✅           |
| create-message-any-team                | ✅               | ✅           |
| create-attachment-any-team             | ✅               | ✅           |
| create-mention-any-team                | ✅               | ✅           |
| create-reaction-any-team               | ✅               | ✅           |
| create-system-message-any-team         | ✅               | ✅           |
| delete-attachment-any-team             | ✅               | ✅           |
| delete-channel-any-team                | ✖️               | ✅           |
| delete-message-any-team                | ✅               | ✅           |
| delete-reaction-any-team               | ✅               | ✅           |
| flag-message-any-team                  | ✅               | ✅           |
| join-call-any-team                     | ✅               | ✅           |
| mute-channel-any-team                  | ✅               | ✅           |
| pin-message-any-team                   | ✅               | ✅           |
| read-channel-any-team                  | ✅               | ✅           |
| read-channel-members-any-team          | ✅               | ✅           |
| read-message-flags-any-team            | ✅               | ✅           |
| recreate-channel-any-team              | ✖️               | ✅           |
| remove-own-channel-membership-any-team | ✅               | ✅           |
| run-message-action-any-team            | ✅               | ✅           |
| send-custom-event-any-team             | ✅               | ✅           |
| skip-channel-cooldown-any-team         | ✅               | ✅           |
| skip-message-moderation-any-team       | ✅               | ✅           |
| truncate-channel-any-team              | ✖️               | ✅           |
| unblock-message-any-team               | ✅               | ✅           |
| update-channel-any-team                | ✅               | ✅           |
| update-channel-cooldown-any-team       | ✅               | ✅           |
| update-channel-frozen-any-team         | ✅               | ✅           |
| update-channel-members-any-team        | ✅               | ✅           |
| update-message-any-team                | ✅               | ✅           |
| upload-attachment-any-team             | ✅               | ✅           |

### Scope `gaming`

| Permission ID                          | global_moderator | global_admin |
| -------------------------------------- | ---------------- | ------------ |
| add-links-any-team                     | ✅               | ✅           |
| ban-channel-member-any-team            | ✅               | ✅           |
| ban-user-any-team                      | ✅               | ✅           |
| create-call-any-team                   | ✅               | ✅           |
| create-channel-any-team                | ✖️               | ✅           |
| create-message-any-team                | ✅               | ✅           |
| create-attachment-any-team             | ✅               | ✅           |
| create-mention-any-team                | ✅               | ✅           |
| create-reaction-any-team               | ✅               | ✅           |
| create-system-message-any-team         | ✅               | ✅           |
| delete-attachment-any-team             | ✅               | ✅           |
| delete-channel-any-team                | ✖️               | ✅           |
| delete-message-any-team                | ✅               | ✅           |
| delete-reaction-any-team               | ✅               | ✅           |
| flag-message-any-team                  | ✅               | ✅           |
| join-call-any-team                     | ✅               | ✅           |
| mute-channel-any-team                  | ✅               | ✅           |
| pin-message-any-team                   | ✅               | ✅           |
| read-channel-any-team                  | ✅               | ✅           |
| read-channel-members-any-team          | ✅               | ✅           |
| read-message-flags-any-team            | ✅               | ✅           |
| recreate-channel-any-team              | ✖️               | ✅           |
| remove-own-channel-membership-any-team | ✅               | ✅           |
| run-message-action-any-team            | ✅               | ✅           |
| send-custom-event-any-team             | ✅               | ✅           |
| skip-channel-cooldown-any-team         | ✅               | ✅           |
| skip-message-moderation-any-team       | ✅               | ✅           |
| truncate-channel-any-team              | ✖️               | ✅           |
| unblock-message-any-team               | ✅               | ✅           |
| update-channel-any-team                | ✖️               | ✅           |
| update-channel-cooldown-any-team       | ✅               | ✅           |
| update-channel-frozen-any-team         | ✅               | ✅           |
| update-channel-members-any-team        | ✖️               | ✅           |
| update-message-any-team                | ✅               | ✅           |
| upload-attachment-any-team             | ✅               | ✅           |

## Team usage statistics

For multi-tenant chat applications, you can query usage statistics broken down by team. This is useful for billing, monitoring, and analytics purposes. The API returns detailed metrics for each team including user counts, message volumes, and activity patterns.

### Querying Team Usage Stats

Use the `queryTeamUsageStats` method to retrieve usage statistics. You can query by month or by a custom date range.

```js label="JavaScript"
// Query current month's stats
const response = await client.queryTeamUsageStats();

// Query specific month
const response = await client.queryTeamUsageStats({ month: "2024-01" });

// Query date range
const response = await client.queryTeamUsageStats({
  start_date: "2024-01-01",
  end_date: "2024-01-31",
});

// With pagination
const response = await client.queryTeamUsageStats({ limit: 10 });
if (response.next) {
  const nextPage = await client.queryTeamUsageStats({
    limit: 10,
    next: response.next,
  });
}
```

```python label="Python"
# Query current month's stats
response = client.chat.query_team_usage_stats()

# Query specific month
response = client.chat.query_team_usage_stats(month="2024-01")

# Query date range
response = client.chat.query_team_usage_stats(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# With pagination
response = client.chat.query_team_usage_stats(limit=10)
if response.data.next:
    next_page = client.chat.query_team_usage_stats(limit=10, next=response.data.next)
```

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

# Query current month's stats
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new)

# Query specific month
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
  month: '2024-01'
))

# Query date range
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
  start_date: '2024-01-01',
  end_date: '2024-01-31'
))

# With pagination
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(limit: 10))
if response.next
  next_page = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
    limit: 10,
    next: response.next
  ))
end
```

```php label="PHP"
// Query current month's stats
$response = $client->queryTeamUsageStats(new Models\QueryTeamUsageStatsRequest());
```

```go label="Go"
// Query current month's stats
response, err := client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{})

// Query specific month
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    Month: getstream.PtrTo("2024-01"),
})

// Query date range
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    StartDate: getstream.PtrTo("2024-01-01"),
    EndDate:   getstream.PtrTo("2024-01-31"),
})

// With pagination
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    Limit: getstream.PtrTo(10),
})
if response.Data.Next != nil && *response.Data.Next != "" {
    nextPage, err := client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
        Limit: getstream.PtrTo(10),
        Next:  response.Data.Next,
    })
    _ = nextPage
    _ = err
}
```

```csharp label="C#"
// Query current month's stats
var response = await statsClient.QueryTeamUsageStatsAsync();

// Query specific month
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    Month = "2024-01"
});

// Query date range
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    StartDate = "2024-01-01",
    EndDate = "2024-01-31"
});

// With pagination
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    Limit = 10
});
if (!string.IsNullOrEmpty(response.Next))
{
    var nextPage = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
    {
        Limit = 10,
        Next = response.Next
    });
}
```

```java label="Java"
// Query current month's stats
var response = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .build()).execute().getData();

// Query specific month
var monthlyResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .month("2024-01")
    .build()).execute().getData();

// Query date range
var rangeResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .startDate("2024-01-01")
    .endDate("2024-01-31")
    .build()).execute().getData();

// With pagination
var pageResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .limit(10)
    .build()).execute().getData();
if (pageResponse.getNext() != null) {
    var nextPage = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
        .limit(10)
        .next(pageResponse.getNext())
        .build()).execute().getData();
}
```

### Available Metrics

The response includes statistics for each team with the following metrics:

| Metric                        | Description                            |
| ----------------------------- | -------------------------------------- |
| `users_daily`                 | Number of unique users active per day  |
| `messages_daily`              | Number of messages sent per day        |
| `translations_daily`          | Number of message translations per day |
| `image_moderations_daily`     | Number of images moderated per day     |
| `concurrent_users`            | Peak concurrent users                  |
| `concurrent_connections`      | Peak concurrent connections            |
| `users_total`                 | Total number of users                  |
| `users_last_24_hours`         | Users active in the last 24 hours      |
| `users_last_30_days`          | Users active in the last 30 days       |
| `users_month_to_date`         | Users active month to date             |
| `users_engaged_last_30_days`  | Engaged users in the last 30 days      |
| `users_engaged_month_to_date` | Engaged users month to date            |
| `messages_total`              | Total number of messages               |
| `messages_last_24_hours`      | Messages sent in the last 24 hours     |
| `messages_last_30_days`       | Messages sent in the last 30 days      |
| `messages_month_to_date`      | Messages sent month to date            |

>
> **Info:** This API requires server-side authentication. It cannot be called from client-side SDKs.
>

>
> **Info:** Use the `month` parameter (format: `YYYY-MM`) for monthly reports, or `start_date` and `end_date` (format: `YYYY-MM-DD`) for custom date ranges. If no parameters are provided, the current month's statistics are returned.
>

### Metric Attribution

Message metrics (`messages_*`) are attributed based on the channel's `team` field (`channel.team`), while user metrics (`users_*`) are attributed based on the user's `teams` array (`user.teams`). This means you may see messages under a team even when `users_*` metrics are zero for that team, if messages were sent in channels belonging to that team by users who are not members of that team.

### Empty Team

The API returns a row for `team=""` (empty string) which represents users and messages that are not assigned to any team. This includes messages in channels without a team set and users without any team membership.

### Response Modes

The response shape differs based on query mode:

**Monthly mode** (using `month` parameter): Returns only the total/aggregated values for each metric. Daily breakdown arrays are omitted.

**Daily mode** (using `start_date` and `end_date`): Returns both daily breakdown arrays and aggregated totals. The aggregation method depends on the metric type:

- **SUM**: Daily activity metrics (`users_daily`, `messages_daily`, `translations_daily`, `image_moderations_daily`) - totals are summed across the date range
- **MAX**: Peak metrics (`concurrent_users`, `concurrent_connections`) - totals reflect the maximum value observed
- **LATEST**: Rolling/cumulative metrics (`users_total`, `users_last_24_hours`, `users_last_30_days`, `users_month_to_date`, `users_engaged_last_30_days`, `users_engaged_month_to_date`, `messages_total`, `messages_last_24_hours`, `messages_last_30_days`, `messages_month_to_date`) - totals reflect the most recent value

### Pagination

Results are paginated in lexicographic order by team name. The `next` cursor in the response is a base64-encoded team ID. Use this cursor value in subsequent requests to fetch the next page of results. The `limit` parameter is capped at 30 teams per request.

### Date Range Validation

When using custom date ranges, the following validations apply:

- `end_date` must be greater than or equal to `start_date`
- The date range cannot exceed 365 days

---

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