Team

This is a detailed reference for the Team object. If you’re looking for a more high-level overview, please refer to our guide on teams.

On this page:

Team

A Team object contains basic information and functions about a team, to the extent of which a member of the team would have access to it.

You can get Team objects with the currentUser.useTeam(...) or currentUser.useTeams() functions. The created team will then inherit the permissions of that user; for example, the team.update(...) function can only succeed if the user is allowed to make updates to the team.

Table of Contents

1type Team = {
2  id: string;  //$stack-link-to:#teamid
3  displayName: string;  //$stack-link-to:#teamdisplayname
4  profileImageUrl: string | null;  //$stack-link-to:#teamprofileimageurl
5  clientMetadata: Json;  //$stack-link-to:#teamclientmetadata
6  clientReadOnlyMetadata: Json;  //$stack-link-to:#teamclientreadonlymetadata
7
8  update(data): Promise<void>;  //$stack-link-to:#teamupdatedata
9  inviteUser(options): Promise<void>;  //$stack-link-to:#teaminviteuseroptions
10  listUsers(): Promise<TeamUser[]>;  //$stack-link-to:#teamlistusers
11   ⤷ useUsers(): TeamUser[];  //$stack-link-to:#teamuseusers
12  listInvitations(): Promise<{ ... }[]>;  //$stack-link-to:#teamlistinvitations
13   ⤷ useInvitations(): { ... }[];  //$stack-link-to:#teamuseinvitations
14};

team.id

The team ID as a string. This value is always unique.

Type Definition

1declare const id: string;

team.displayName

The display name of the team as a string.

Type Definition

1declare const displayName: string;

team.profileImageUrl

The profile image URL of the team as a string, or null if no profile image is set.

Type Definition

1declare const profileImageUrl: string | null;

team.clientMetadata

The client metadata of the team as a Json object.

Type Definition

1declare const clientMetadata: Json;

team.clientReadOnlyMetadata

The client read-only metadata of the team as a Json object.

Type Definition

1declare const clientReadOnlyMetadata: Json;

team.update(data)

Updates the team information.

Note that this operation requires the current user to have the $update_team permission. If the user lacks this permission, an error will be thrown.

Parameters

data
TeamUpdateOptionsRequired

The fields to update.

Returns

Promise<void>

Signature

1declare function update(options: {
2  displayName?: string;
3  profileImageUrl?: string | null;
4  clientMetadata?: Json;
5}): Promise<void>;

Examples

1await team.update({
2  displayName: 'New Team Name',
3  profileImageUrl: 'https://example.com/profile.png',
4  clientMetadata: {
5    address: '123 Main St, Anytown, USA',
6  },
7});

team.inviteUser(options)

Sends an invitation email to a user to join the team.

Note that this operation requires the current user to have the $invite_members permission. If the user lacks this permission, an error will be thrown.

An invitation email containing a magic link will be sent to the specified user. If the user has an existing account, they will be automatically added to the team upon clicking the link. For users without an account, the link will guide them through the sign-up process before adding them to the team.

Parameters

options
objectRequired

An object containing multiple properties.

Returns

Promise<void>

Signature

1declare function inviteUser(options: {
2  email: string;
3  callbackUrl?: string;
4}): Promise<void>;

Examples

1await team.inviteUser({
2  email: 'user@example.com',
3});

team.listUsers()

Gets a list of users in the team.

Note that this operation requires the current user to have the $read_members permission. If the user lacks this permission, an error will be thrown.

Parameters

None.

Returns

Promise<TeamUser[]>

Signature

1declare function listUsers(): Promise<TeamUser[]>;

Examples

1const users = await team.listUsers();
2users.forEach(user => {
3  console.log(user.id, user.teamProfile.displayName);
4});

team.useUsers()

Functionally equivalent to listUsers(), but as a React hook.

Parameters

None.

Returns

TeamUser[]

Signature

1declare function useUsers(): TeamUser[];

Examples

1const users = team.useUsers();
2users.forEach(user => {
3  console.log(user.id, user.teamProfile.displayName);
4});

team.listInvitations()

Gets a list of invitations to the team.

Note that this operation requires the current user to have the $read_members and $invite_members permissions. If the user lacks this permission, an error will be thrown.

Parameters

None.

Returns

Promise<{ id: string, email: string, expiresAt: Date }[]>

Signature

1declare function listInvitations(): Promise<{ id: string, email: string, expiresAt: Date }[]>;

Examples

1const invitations = await team.listInvitations();
2invitations.forEach(invitation => {
3  console.log(invitation.id, invitation.email);
4});

team.useInvitations()

Functionally equivalent to listInvitations(), but as a React hook.

Parameters

None.

Returns

{ id: string, email: string, expiresAt: Date }[]

Signature

1declare function useInvitations(): { id: string, email: string, expiresAt: Date }[];

Examples

1const invitations = team.useInvitations();
2invitations.forEach(invitation => {
3  console.log(invitation.id, invitation.email);
4});

ServerTeam

Like Team, but with server permissions. Has full read and write access to everything.

Calling serverUser.getTeam(...) and serverUser.listTeams() will return ServerTeam objects if the user is a ServerUser. Alternatively, you can call stackServerApp.getTeam('team_id_123') or stackServerApp.listTeams() to query all teams of the project.

ServerTeam extends the Team object, providing additional functions and properties as detailed below. It’s important to note that while the Team object’s functions may require specific user permissions, the corresponding functions in ServerTeam can be executed without these permission checks. This allows for more flexible and unrestricted team management on the server side.

Table of Contents

1type ServerTeam =
2  // Inherits all functionality from Team
3  & Team //$stack-link-to:#team
4  & {
5    createdAt: Date;  //$stack-link-to:#serverteamcreatedat
6    serverMetadata: Json;  //$stack-link-to:#serverteamservermetadata
7
8    listUsers(): Promise<ServerTeamUser[]>;  //$stack-link-to:#serverteamlistusers
9     ⤷ useUsers(): ServerTeamUser[];  //$stack-link-to:#serverteamuseusers
10    addUser(userId): Promise<void>;  //$stack-link-to:#serverteamadduseruserid
11    removeUser(userId): Promise<void>;  //$stack-link-to:#serverteamremoveuseruserid
12    delete(): Promise<void>;  //$stack-link-to:#serverteamdelete
13  };

serverTeam.createdAt

The date and time when the team was created.

Type Definition

1declare const createdAt: Date;

serverTeam.serverMetadata

The server metadata of the team as a Json object.

Type Definition

1declare const serverMetadata: Json;

serverTeam.listUsers()

Gets a list of users in the team.

This is similar to the listUsers method on the Team object, but it returns ServerTeamUser objects instead of TeamUser objects and does not require any permissions.

Parameters

None.

Returns

Promise<ServerTeamUser[]>

Signature

1declare function listUsers(): Promise<ServerTeamUser[]>;

Examples

1const users = await team.listUsers();
2users.forEach(user => {
3  console.log(user.id, user.teamProfile.displayName);
4});

serverTeam.useUsers()

This is the documentation for a React hook on a server type. This is uncommon, because server types are only available with server permissions and React Server Components do not use hooks. Ask yourself if you:

  • Want to use this on the server, eg. in a React Server Component? Look for the respective function without the use prefix (eg. getUser instead of useUser).
  • Want to use this on the client, eg. in a React Client Component? Look at the documentation of the client type (eg. CurrentUser instead of CurrentServerUser).
  • Are an advanced user, building an internal tool, and confident that you are securing SECRET_SERVER_KEY correctly? Then this is for you.

Functionally equivalent to listUsers(), but as a React hook.

serverTeam.addUser(userId)

Adds a user to the team directly without sending an invitation email.

Parameters

userId
stringRequired

The ID of the user to add.

Returns

Promise<void>

Signature

1declare function addUser(userId: string): Promise<void>;

Examples

1await team.addUser('user_id_123');

serverTeam.removeUser(userId)

Removes a user from the team.

Parameters

userId
stringRequired

The ID of the user to remove.

Returns

Promise<void>

Signature

1declare function removeUser(userId: string): Promise<void>;

Examples

1await team.removeUser('user_id_123');

serverTeam.delete()

Deletes the team.

Parameters

None.

Returns

Promise<void>

Signature

1declare function delete(): Promise<void>;

Examples

1await team.delete();