Teams
Manage teams and team members
Teams provide a structured way to group users and manage their permissions. Users can belong to multiple teams simultaneously, allowing them to represent departments, B2B customers, or projects.
The server can perform all operations on a team, but the client can only carry out some actions if the user has the necessary permissions. This applies to all actions that can be performed on a server/client-side User
object and a Team
object.
Concepts
Team permissions
If you attempt to perform an action without the necessary team permissions, the function will throw an error. Always check if the user has the required permission before performing any action. Learn more about permissions here.
Here is an example of how to check if a user has a specific permission on the client
Team profile
A user can have a different profile for each team they belong to (Note this is different to the user’s personal profile). This profile contains information like displayName
and profileImageUrl
. The team profile can be left empty and it will automatically take the user’s personal profile information.
The team profile is visible to all the other users in the team that have the $read_members
permission.
Retrieving a user’s teams
You can list all teams a user belongs to using the listTeams
or useTeams
functions or fetch a specific team with getTeam
or useTeam
. These functions work on both clients and servers.
Client Component
Server Component
Creating a team
To create a team, use the createTeam
function on the User
object. The user will be added to the team with the default team creator permissions (You can change this on the permissions tab in the Stack dashboard).
On the client side, this requires enabling the “client side team creation” on the team settings tab in the Stack dashboard.
To create a team on the server without adding a specific user, use the createTeam
function on the ServerApp
object:
Updating a team
You can update a team with the update
function on the Team
object.
On the client, the user must have the $update_team
permission to perform this action.
Custom team metadata
You can store custom metadata on a team object, similar to the user object. The metadata can be any JSON object.
clientMetadata
: Can be read and updated on both the client and server sides.serverMetadata
: Can only be read and updated on the server side.clientReadOnlyMetadata
: Can be read on both the client and server sides, but can only be updated on the server side.
List users in a team
You can list all users in a team with the listUsers
function or the useUsers
hook on the Team
object. Note that if you want to get the team profile, you need to get it with user.teamProfile
.
On the client, the current user must have the $read_members
permission in the team to perform this action.
Client Component
Server Component
Get current user’s team profile
You can get the current user’s team profile with the getTeamProfile
or useTeamProfile
function on the User
object. This function returns the team profile for the team with the given ID.
Client Component
Server Component
Invite a user to a team
You can invite a user to a team using the inviteUser
function on the Team
object. The user will receive an email with a link to join the team.
On the client side, the current user must have the $invite_members
permission to perform this action.
Adding a user to a team
If you want to add a user to a team without sending an email, use the addUser
function on the ServerTeam
object. This function can only be called on the server side.
Removing a user from a team
You can remove a user from a team with the removeUser
function on the Team
object.
On the client side, the current user must have the $remove_members
permission to perform this action.
Leaving a team
All users can leave a team without any permissions required.
Deleting a team
You can delete a team with the delete
function on the Team
object.
On the client side, the current user must have the $delete_team
permission to perform this action.