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
user.useTeams() or
user.listTeams() 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
The team ID as a string. This value is always unique.
declare const id: string;The display name of the team as a string.
declare const displayName: string;The profile image URL of the team as a string, or null if no profile image is set.
declare const profileImageUrl: string | null;The client metadata of the team as a Json object.
declare const clientMetadata: Json;The client read-only metadata of the team as a Json object.
declare const clientReadOnlyMetadata: Json;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
dataTeamUpdateOptionsrequiredThe fields to update.
Show Properties
displayNamestringThe display name of the team.
profileImageUrlstring | nullThe profile image URL of the team.
clientMetadataJsonThe client metadata of the team.
Returns
Promise<void>
declare function update(options: {
displayName?: string;
profileImageUrl?: string | null;
clientMetadata?: Json;
}): Promise<void>;await team.update({
displayName: 'New Team Name',
profileImageUrl: 'https://example.com/profile.png',
clientMetadata: {
address: '123 Main St, Anytown, USA',
},
});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
optionsobjectrequiredAn object containing multiple properties.
Show Properties
emailstringrequiredThe email of the user to invite.
callbackUrlstringThe URL where users will be redirected after accepting the team invitation.
Required when calling inviteUser() in the server environment since the URL cannot be automatically determined.
Example: https://your-app-url.com/handler/team-invitation
Returns
Promise<void>
declare function inviteUser(options: {
email: string;
callbackUrl?: string;
}): Promise<void>;await team.inviteUser({
email: 'user@example.com',
});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[]>
declare function listUsers(): Promise<TeamUser[]>;const users = await team.listUsers();
users.forEach(user => {
console.log(user.id, user.teamProfile.displayName);
});declare function useUsers(): TeamUser[];const users = team.useUsers();
users.forEach(user => {
console.log(user.id, user.teamProfile.displayName);
});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 }[]>
declare function listInvitations(): Promise<{ id: string, email: string, expiresAt: Date }[]>;const invitations = await team.listInvitations();
invitations.forEach(invitation => {
console.log(invitation.id, invitation.email);
});Functionally equivalent to listInvitations(), but as a React hook.
Parameters
None.
Returns
{ id: string, email: string, expiresAt: Date }[]
declare function useInvitations(): { id: string, email: string, expiresAt: Date }[];const invitations = team.useInvitations();
invitations.forEach(invitation => {
console.log(invitation.id, invitation.email);
});Creates a new API key for the team.
Parameters
optionsobjectrequiredAn object containing multiple properties.
Show Properties
namestringrequiredThe name of the API key.
descriptionstringThe description of the API key.
expiresAtDaterequiredThe expiration date of the API key.
Returns
Promise<TeamApiKeyFirstView>
declare function createApiKey(options: {
name: string;
description: string;
expiresAt: Date;
}): Promise<TeamApiKeyFirstView>;await team.createApiKey({
name: 'New API Key',
description: 'This is a new API key',
expiresAt: new Date('2024-01-01'),
});declare function listApiKeys(): Promise<TeamApiKey[]>;const apiKeys = await team.listApiKeys();
apiKeys.forEach(key => {
console.log(key.id, key.name);
});declare function useApiKeys(): TeamApiKey[];const apiKeys = team.useApiKeys();
apiKeys.forEach(key => {
console.log(key.id, key.name);
});Creates a checkout URL for the team to purchase products. This method integrates with Stripe to generate a secure payment link for team-level purchases.
Note that this operation requires the current user to have appropriate permissions for team purchases. The specific permission requirements depend on your project configuration.
Parameters
optionsobjectrequiredOptions for creating the checkout URL.
Show Properties
productIdstringrequiredThe ID of the product to purchase.
Returns
Promise<string>: A URL that redirects to the Stripe checkout page for the specified product.
declare function createCheckoutUrl(options: {
productId: string;
}): Promise<string>;const checkoutUrl = await team.createCheckoutUrl({
productId: "prod_team_seats",
});
// Redirect to checkout
window.location.href = checkoutUrl;Retrieves information about a specific item (such as credits, API quotas, storage limits, etc.) for the team.
Parameters
itemIdstringrequiredThe ID of the item to retrieve.
Returns
Promise<Item>: The item object containing display name, quantity, and other details.
declare function getItem(itemId: string): Promise<Item>;const apiQuota = await team.getItem("api_calls");
console.log(`Team has ${apiQuota.quantity} API calls remaining`);
if (apiQuota.nonNegativeQuantity < 100) {
console.warn("Team is running low on API calls");
}Retrieves information about a specific item for the team, used as a React hook.
Parameters
itemIdstringrequiredThe ID of the item to retrieve.
Returns
Item: The item object containing display name, quantity, and other details.
declare function useItem(itemId: string): Item;function TeamQuotaDisplay({ team }: { team: Team }) {
const storage = team.useItem("storage_gb");
return (
<div>
<h3>Team Storage Usage</h3>
<p>{storage.quantity} GB used</p>
<p>Plan: {storage.displayName}</p>
</div>
);
}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
The date and time when the team was created.
declare const createdAt: Date;The server metadata of the team as a Json object.
declare const serverMetadata: Json;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[]>
declare function listUsers(): Promise<ServerTeamUser[]>;const users = await team.listUsers();
users.forEach(user => {
console.log(user.id, user.teamProfile.displayName);
});declare function useUsers(): ServerTeamUser[];const users = team.useUsers();
users.forEach(user => {
console.log(user.id, user.teamProfile.displayName);
});Adds a user to the team directly without sending an invitation email.
Parameters
userIdstringrequiredThe ID of the user to add.
Returns
Promise<void>
declare function addUser(userId: string): Promise<void>;await team.addUser('user_id_123');Removes a user from the team.
Parameters
userIdstringrequiredThe ID of the user to remove.
Returns
Promise<void>
declare function removeUser(userId: string): Promise<void>;Examples
await team.removeUser('user_id_123');declare function delete(): Promise<void>;await team.delete();