> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Team
> Reference for Team and ServerTeam types for team management.
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](https://docs.hexclave.com/guides/apps/teams/overview.md).On this page:- [Team](#team)
- [ServerTeam](#serverteam)***# `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 ContentsTeam Table of Contents## Properties
\
\`team.id`
team
Unique team identifier.
Type Definition
\`typescript declare const id: string; `
\
\
\`team.displayName`
team
The display name of the team.
Type Definition
\`typescript declare const displayName: string; `
\
\
\`team.profileImageUrl`
team
The profile image URL of the team, or `null` if no profile image is set.
Type Definition
\`typescript declare const profileImageUrl: string | null; `
\
\
\`team.clientMetadata`
team
Custom metadata accessible to clients.
Type Definition
\`typescript declare const clientMetadata: Json; `
\
\
\`team.clientReadOnlyMetadata`
team
Read-only metadata for clients.
Type Definition
\`typescript declare const clientReadOnlyMetadata: Json; `
\
## Methods
\
\`team.update(data)`
team
Updates the team information. Requires the current user to have the `$update_team` permission.
Parameters
\**data** `object` *required*
The fields to update on the team.
\**displayName** `string`
The display name of the team.
\**profileImageUrl** `string | null`
The profile image URL of the team.
\**clientMetadata** `Json`
The client metadata of the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function update(data: {
displayName?: string;
profileImageUrl?: string | null;
clientMetadata?: Json;
}): Promise;
\```
Examples
\```typescript theme={null}
await team.update({
displayName: "New Team Name",
profileImageUrl: "https://example.com/profile.png",
clientMetadata: {
address: "123 Main St, Anytown, USA",
},
});
\```
\
\
\`team.delete`
team
Deletes the team. Requires the current user to have the `$delete_team` permission.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function delete(): Promise;
\```
\
\
\`team.inviteUser(options)`
team
Sends an invitation email to a user to join the team. Requires the `$invite_members` permission.
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.email** `string` *required*
The email of the user to invite.
\**options.callbackUrl** `string`
The URL where users will be redirected after accepting the team invitation. This is required in server environments.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function inviteUser(options: {
email: string;
callbackUrl?: string;
}): Promise;
\```
Examples
\```typescript theme={null}
await team.inviteUser({
email: "user@example.com",
});
\```
\
\
\`team.listUsers`
team
Gets a list of users in the team. Requires the `$read_members` permission.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listUsers(): Promise;
\```
Examples
\```typescript theme={null}
const users = await team.listUsers();
users.forEach((user) => {
console.log(user.id, user.teamProfile.displayName);
});
\```
\
\
\`team.useUsers`
team
React hook version of `listUsers()`.
Returns
\`TeamUser[]`
Signature
\```typescript theme={null}
declare function useUsers(): TeamUser[];
\```
\
\
\`team.listInvitations`
team
Gets a list of invitations to the team. Requires the `$read_members` and `$invite_members` permissions.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listInvitations(): Promise;
\```
Examples
\```typescript theme={null}
const invitations = await team.listInvitations();
invitations.forEach((invitation) => {
console.log(invitation.id, invitation.recipientEmail);
});
\```
\
\
\`team.useInvitations`
team
React hook version of `listInvitations()`.
Returns
\`SentTeamInvitation[]`
Signature
\```typescript theme={null}
declare function useInvitations(): SentTeamInvitation[];
\```
\
## API Keys
\
\`team.createApiKey(options)`
team
Creates a new API key for the team.
Parameters
\**options.name** `string` *required*
The name of the API key.
\**options.description** `string`
The description of the API key.
\**options.expiresAt** `Date` *required*
The expiration date of the API key.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function createApiKey(options: {
name: string;
description?: string;
expiresAt: Date;
}): Promise;
\```
Examples
\```typescript theme={null}
await team.createApiKey({
name: "New API Key",
description: "This is a new API key",
expiresAt: new Date("2024-01-01"),
});
\```
\
\
\`team.listApiKeys`
team
Gets a list of API keys for the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listApiKeys(): Promise;
\```
\
\
\`team.useApiKeys`
team
React hook version of `listApiKeys()`.
Returns
\`TeamApiKey[]`
Signature
\```typescript theme={null}
declare function useApiKeys(): TeamApiKey[];
\```
\
## Billing & Payments
\
\`team.createCheckoutUrl(options)`
team
Creates a checkout URL for the team to purchase products. Integrates with Stripe to generate a secure payment link.
Parameters
\**options.productId** `string`
The ID of the product to purchase.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function createCheckoutUrl(options: {
productId: string;
}): Promise;
\```
Examples
\```typescript theme={null}
const checkoutUrl = await team.createCheckoutUrl({
productId: "prod_team_seats",
});
window.location.href = checkoutUrl;
\```
\
\
\`team.getItem(itemId)`
team
Retrieves information about a specific item, such as credits, API quotas, or storage limits, for the team.
Parameters
\**itemId** `string`
The ID of the item to retrieve.
Returns
\`Promise- `
Signature
\```typescript theme={null}
declare function getItem(itemId: string): Promise
- ;
\```
Examples
\```typescript theme={null}
const apiQuota = await team.getItem("api_calls");
console.log(`Team has ${apiQuota.quantity} API calls remaining`);
\```
\
\
\`team.useItem(itemId)`
team
React hook version of `getItem()`.
Parameters
\**itemId** `string`
The ID of the item to retrieve.
Returns
\`Item`
Signature
\```typescript theme={null}
declare function useItem(itemId: string): Item;
\```
\
\
\`team.createPaymentMethodSetupIntent`
team
Creates a Stripe setup intent for adding a payment method to the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function createPaymentMethodSetupIntent(): Promise;
\```
\
\
\`team.setDefaultPaymentMethodFromSetupIntent(setupIntentId)`
team
Sets the default payment method from a completed setup intent.
Parameters
\**setupIntentId** `string` *required*
The ID of the completed setup intent.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function setDefaultPaymentMethodFromSetupIntent(
setupIntentId: string,
): Promise;
\```
\
\
\`team.switchSubscription(options)`
team
Switches a subscription from one product to another.
Parameters
\**options** `object` *required*
Subscription switch options.
\**fromProductId** `string` *required*
The product ID to switch from.
\**toProductId** `string` *required*
The product ID to switch to.
\**priceId** `string`
A specific price ID to use.
\**quantity** `number`
The quantity for the new subscription.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function switchSubscription(options: {
fromProductId: string;
toProductId: string;
priceId?: string;
quantity?: number;
}): Promise;
\```
\
\
\`team.getBilling`
team
Returns the billing information for the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function getBilling(): Promise;
\```
\
\
\`team.useBilling`
team
React hook that returns the billing information.
Returns
\`CustomerBilling`
Signature
\```typescript theme={null}
declare function useBilling(): CustomerBilling;
\```
\
\
\`team.listProducts([options])`
team
Returns all products available to the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listProducts(options?: CustomerProductsListOptions): Promise;
\```
\
\
\`team.useProducts([options])`
team
React hook that returns all products.
Returns
\`CustomerProductsList`
Signature
\```typescript theme={null}
declare function useProducts(options?: CustomerProductsListOptions): CustomerProductsList;
\```
\
\
\`team.listInvoices([options])`
team
Returns all invoices for the team.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listInvoices(options?: CustomerInvoicesListOptions): Promise;
\```
\
\
\`team.useInvoices([options])`
team
React hook that returns all invoices.
Returns
\`CustomerInvoicesList`
Signature
\```typescript theme={null}
declare function useInvoices(options?: CustomerInvoicesListOptions): CustomerInvoicesList;
\```
\
***# `ServerTeam`Like [`Team`](#team), but with server permissions through [`HexclaveServerApp`](https://docs.hexclave.com/sdk/objects/hexclave-app#hexclaveserverapp). Has full read and write access to everything.Calling `serverUser.getTeam(...)` and `serverUser.listTeams()` will return `ServerTeam` objects if the user is a [`ServerUser`](https://docs.hexclave.com/sdk/types/user#serveruser). Alternatively, you can call `hexclaveServerApp.getTeam('team_id_123')` or `hexclaveServerApp.listTeams()` to query all teams of the project.`ServerTeam` extends the `Team` object, providing additional functions and properties. While the `Team` object's functions may require specific user permissions, the corresponding functions in `ServerTeam` can be executed without these permission checks.## Table of ContentsServerTeam Table of Contents## Additional Properties
\
\`serverTeam.createdAt`
serverTeam
The date and time when the team was created.
Type Definition
\`typescript declare const createdAt: Date; `
\
\
\`serverTeam.serverMetadata`
serverTeam
Server-only metadata.
Type Definition
\`typescript declare const serverMetadata: Json; `
\
## Additional Methods
\
\`serverTeam.update(data)`
serverTeam
Extended update supporting server-only fields. Does not require any permissions.
Parameters
\**data** `ServerTeamUpdateOptions` *required*
The fields to update on the team.
\**displayName** `string`
The display name of the team.
\**profileImageUrl** `string | null`
The profile image URL of the team.
\**clientMetadata** `ReadonlyJson`
Client metadata.
\**clientReadOnlyMetadata** `ReadonlyJson`
Client read-only metadata.
\**serverMetadata** `ReadonlyJson`
Server-only metadata.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function update(data: ServerTeamUpdateOptions): Promise;
\```
Examples
\```typescript theme={null}
await serverTeam.update({
displayName: "Updated Team Name",
serverMetadata: { internalTag: "enterprise" },
});
\```
\
\
\`serverTeam.listUsers`
serverTeam
Gets a list of users in the team. Returns `ServerTeamUser` objects and does not require any permissions.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listUsers(): Promise;
\```
Examples
\```typescript theme={null}
const users = await team.listUsers();
users.forEach((user) => {
console.log(user.id, user.teamProfile.displayName);
});
\```
\
\
\`serverTeam.useUsers`
serverTeam
React hook version of `listUsers()`.
Returns
\`ServerTeamUser[]`
Signature
\```typescript theme={null}
declare function useUsers(): ServerTeamUser[];
\```
\
\
\`serverTeam.addUser(userId)`
serverTeam
Adds a user to the team directly without sending an invitation email.
Parameters
\**userId** `string`
The ID of the user to add.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function addUser(userId: string): Promise;
\```
Examples
\```typescript theme={null}
await team.addUser("user_id_123");
\```
\
\
\`serverTeam.removeUser(userId)`
serverTeam
Removes a user from the team.
Parameters
\**userId** `string`
The ID of the user to remove.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function removeUser(userId: string): Promise;
\```
Examples
\```typescript theme={null}
await team.removeUser("user_id_123");
\```
\
***# Types### `TeamCreateOptions`Options for creating a team via [`user.createTeam()`](https://docs.hexclave.com/sdk/types/user#currentusercreateteam).**displayName** `string` *required*The display name for the team.**profileImageUrl** `string`The profile image URL for the team.### `ServerTeamCreateOptions`Extended creation options available on the server.**displayName** `string` *required*The display name for the team.**profileImageUrl** `string`The profile image URL for the team.**creatorUserId** `string`The user ID of the team creator. If not set, the team is created without a creator.### `TeamUpdateOptions`Options for updating a team via [`team.update()`](#teamupdate).**displayName** `string`The display name of the team.**profileImageUrl** `string | null`The profile image URL of the team.**clientMetadata** `ReadonlyJson`Client metadata.### `ServerTeamUpdateOptions`Extended update options available on the server via [`serverTeam.update()`](#serverteamupdate).**displayName** `string`The display name of the team.**profileImageUrl** `string | null`The profile image URL of the team.**clientMetadata** `ReadonlyJson`Client metadata.**clientReadOnlyMetadata** `ReadonlyJson`Client read-only metadata.**serverMetadata** `ReadonlyJson`Server-only metadata.***# Invitation Types### `SentTeamInvitation`Represents an invitation that was sent from a team. Returned by [`team.listInvitations()`](#teamlistinvitations).**id** `string`The unique identifier for the invitation.**recipientEmail** `string | null`The email address of the invited user, or `null` if not specified.**expiresAt** `Date`The date and time when the invitation expires.```typescript theme={null}
declare function revoke(): Promise;
```The `revoke()` method cancels the invitation.### `ReceivedTeamInvitation`Represents an invitation received by a user. Returned by [`user.listTeamInvitations()`](https://docs.hexclave.com/sdk/types/user#currentuserlistteaminvitations).**id** `string`The unique identifier for the invitation.**teamId** `string`The ID of the team that sent the invitation.**teamDisplayName** `string`The display name of the inviting team.**recipientEmail** `string`The email address the invitation was sent to.**expiresAt** `Date`The date and time when the invitation expires.```typescript theme={null}
declare function accept(): Promise;
```The `accept()` method accepts the invitation and adds the user to the team.