API Key: {apiKey.value}
;
@@ -467,7 +512,7 @@ Users with appropriate permissions can manage team API keys directly from the te
const handleCreateKey = async () => {
const apiKey = await user.createApiKey({
description: "My client application",
- expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
+ expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
});
console.log("API Key created:", apiKey.value);
@@ -480,6 +525,7 @@ Users with appropriate permissions can manage team API keys directly from the te
Team not found
;
- }
+ if (!team) return Team not found
;
const teamApiKey = await team.createApiKey({
description: "Admin-provisioned team API key",
- expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
+ expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
});
return Team API Key: {teamApiKey.value}
;
@@ -638,7 +683,7 @@ Users with appropriate permissions can manage team API keys directly from the te
const teamApiKey = await team.createApiKey({
description: "Team integration service",
- expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
+ expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000), // 60 days
});
console.log("Team API Key created:", teamApiKey.value);
@@ -749,7 +794,7 @@ Users with appropriate permissions can manage team API keys directly from the te
Check out our new feature!
', + subject: 'Product Updates', + notificationCategoryName: 'Marketing', +}); +``` + +If a user has unsubscribed from Marketing emails, the email will be automatically skipped during delivery. Marketing emails always include an unsubscribe link. + ## Sending emails Emails are sent from your server using `stackServerApp.sendEmail()`. You must provide the content (HTML, a template, or a draft) and the recipients. @@ -46,7 +94,7 @@ await stackServerApp.sendEmail({ ### Send from a dashboard draft -If you've composed an email in the dashboard's draft editor, you can trigger it programmatically: +If you've composed an email in the dashboard's draft editor, you can trigger it programmatically. See [Drafts](/guides/apps/emails/drafts) for the full workflow. ```typescript await stackServerApp.sendEmail({ @@ -94,7 +142,7 @@ type SendEmailOptions = { ```Hi {user.displayName}, check out {variables.featureName}!
-- Unsubscribe -
- )} - -Check out our new feature!
', - subject: 'Product Updates', - notificationCategoryName: 'Marketing', -}); -``` - -If a user has unsubscribed from Marketing emails, the email will be automatically skipped during delivery. Marketing emails always include an unsubscribe link. - ## React components integration -Emails integrate with Stack Auth UI components automatically (for example verification, password reset, and magic-link flows). +Emails integrate with Stack Auth UI components automatically (for example verification, password reset, and magic-link flows). Each of those flows uses a built-in template that you can customize in [Templates](/guides/apps/emails/templates). + For custom flows, trigger `sendEmail` from your server code: ```typescript @@ -282,69 +209,9 @@ export async function inviteUser(userId: string) { } ``` -## Email server configuration - -Configure your email server in the dashboard under **Emails → Email Settings**. There are four options: - -### Shared (development only) - -The default for new projects. Emails are sent from `noreply@stackframe.co` using Stack Auth's shared infrastructure. Good for development - not suitable for production. - -### Custom SMTP - -Connect any SMTP provider. Configure: - -- **Host** - e.g. `smtp.sendgrid.net` -- **Port** - typically 587 (STARTTLS) or 465 (implicit TLS) -- **Username** and **Password** -- **Sender email** and **Sender name** - -### Resend - -Connect your [Resend](https://resend.com) account by entering your API key. Stack Auth configures the SMTP connection automatically. - -### Managed - -Let Stack Auth manage your email domain. Stack Auth handles DNS configuration and deliverability for you. Set up requires: - -1. Choose a subdomain (e.g. `mail.yourapp.com`) -2. Add the DNS records Stack Auth provides -3. Verify the domain in the dashboard - -Hi {user.displayName}, check out {variables.featureName}!
++ Unsubscribe +
+ )} + +
+
+ );
+}
+```
+
+### Consuming items safely
+
+When a user spends credits, use `tryDecreaseQuantity` on the server. It is atomic and race-condition-safe: if the balance would go negative, it returns `false` and leaves the balance unchanged.
+
+```typescript title="lib/credits.ts"
+import { stackServerApp } from "@/stack/server";
+
+export async function consumeCredits(userId: string, amount: number) {
+ const user = await stackServerApp.getUser(userId);
+ if (!user) throw new Error("User not found");
+
+ const credits = await user.getItem("credits");
+ const success = await credits.tryDecreaseQuantity(amount);
+
+ if (!success) {
+ throw new Error("Insufficient credits");
+ }
+
+ return { remaining: credits.quantity };
+}
+```
+
+You can also increase a balance with `credits.increaseQuantity(amount)` or decrease without the safety check using `credits.decreaseQuantity(amount)`.
diff --git a/docs-mintlify/guides/apps/payments/settings.mdx b/docs-mintlify/guides/apps/payments/settings.mdx
new file mode 100644
index 0000000000..3e58236457
--- /dev/null
+++ b/docs-mintlify/guides/apps/payments/settings.mdx
@@ -0,0 +1,126 @@
+---
+title: "Settings"
+description: "Connect Stripe, toggle test mode, pick payment methods, and block new purchases"
+---
+
+The **Settings** page (`Payments -> Settings`) is where Payments is wired up — Stripe connection, test-mode behavior, accepted payment methods, and a kill switch for new purchases.
+
+## Stripe connection
+
+The **Stripe Connection** card at the top of the page reflects the current state of the underlying Stripe Connect account. It shows one of three states:
+
+- **Not connected** *(red)* — no Stripe account is linked yet. A **Connect Stripe** button launches Stripe's hosted onboarding flow. After completing onboarding, you're redirected back to this page.
+- **Setup incomplete** *(orange)* — Stripe started onboarding but hasn't finished. The card lists missing capabilities as badges (e.g. **Charge customers**, **Receive payouts**) and offers a **Continue setup** button that resumes the hosted flow.
+- **Connected** *(green)* — Stripe is fully set up. The card lists the enabled capabilities as badges (typically **Charges enabled** and **Payouts enabled**).
+
+The state is read live via `useStripeAccountInfo()`. Reconnecting or onboarding always pushes you out to Stripe's hosted flow; Stack Auth never collects bank or identity information directly.
+
+## Test mode
+
+The **Test Mode** card has a single switch. Toggling it takes effect immediately for both the dashboard and SDKs.
+
+When **Test mode is active**, the card turns blue and surfaces three badges describing the runtime behavior:
+
+- **No credit card required**
+- **Products granted instantly**
+- **No Stripe transactions**
+
+In test mode, every checkout URL short-circuits — the product is granted directly to the customer without a redirect to Stripe and without any real money moving. This is the recommended mode for local development, end-to-end tests, and demos.
+
+Available Credits
+{credits.nonNegativeQuantity}
+
@@ -104,7 +192,8 @@ To get a list of all permissions a user has, use the `listPermissions` method or
export default async function DisplayUserPermissions() {
const user = await stackServerApp.getUser({ or: 'redirect' });
- const permissions = await user.listPermissions();
+ const team = await stackServerApp.getTeam('some-team-id');
+ const permissions = team ? await user.listPermissions(team) : [];
return (
@@ -125,6 +214,7 @@ To grant a permission to a user, use the `grantPermission` method on the `Server
```tsx
const team = await stackServerApp.getTeam('teamId');
const user = await stackServerApp.getUser();
+if (!team || !user) throw new Error("Team or user not found");
await user.grantPermission(team, 'read');
```
@@ -135,6 +225,7 @@ To revoke a permission from a user, use the `revokePermission` method on the `Se
```tsx
const team = await stackServerApp.getTeam('teamId');
const user = await stackServerApp.getUser();
+if (!team || !user) throw new Error("Team or user not found");
await user.revokePermission(team, 'read');
```
@@ -144,11 +235,11 @@ Project permissions are global permissions that apply to a user across the entir
### Creating a Project Permission
-To create a new project permission, navigate to the `Project Permissions` section of the Stack dashboard. Similar to team permissions, you can select other permissions that the new permission will contain, creating a hierarchical structure.
+To create a new project permission, navigate to **RBAC -> Project Permissions** in the Stack dashboard. Similar to team permissions, you can set an ID, add a description, and select other project permissions that the new permission contains.
### Checking if a User has a Project Permission
-To check whether a user has a specific project permission, use the `getPermission` method or the `usePermission` hook. Here's an example:
+To check whether a user has a specific project permission, use `hasPermission`, `getPermission`, or the `usePermission` hook. Here's an example:
@@ -186,9 +277,26 @@ To check whether a user has a specific project permission, use the `getPermissio
+For authorization logic, prefer a server-side boolean check:
+
+```tsx title="app/admin/page.tsx"
+import { stackServerApp } from "@/stack/server";
+
+export default async function AdminPage() {
+ const user = await stackServerApp.getUser({ or: "redirect" });
+ const canAccessAdmin = await user.hasPermission("access_admin_dashboard");
+
+ if (!canAccessAdmin) {
+ return
@@ -198,7 +306,7 @@ To get a list of all global permissions a user has, use the `listPermissions` me
export function DisplayGlobalPermissions() {
const user = useUser({ or: 'redirect' });
- const permissions = user.usePermissions();
+ const permissions = user.usePermissions({ recursive: false });
return (
Access denied
;
+ }
+
+ return Admin dashboard
;
+}
+```
+
### Listing All Project Permissions
-To get a list of all global permissions a user has, use the `listPermissions` method or the `usePermissions` hook:
+To get a list of all global permissions a user has, use the `listPermissions` method or the `usePermissions` hook. Pass `{ recursive: false }` if you only want direct grants:
@@ -216,7 +324,7 @@ To get a list of all global permissions a user has, use the `listPermissions` me
export default async function DisplayGlobalPermissions() {
const user = await stackServerApp.getUser({ or: 'redirect' });
- const permissions = await user.listPermissions();
+ const permissions = await user.listPermissions({ recursive: false });
return (
@@ -236,6 +344,7 @@ To grant a global permission to a user, use the `grantPermission` method:
```tsx
const user = await stackServerApp.getUser();
+if (!user) throw new Error("User not found");
await user.grantPermission('access_admin_dashboard');
```
@@ -245,7 +354,25 @@ To revoke a global permission from a user, use the `revokePermission` method:
```tsx
const user = await stackServerApp.getUser();
+if (!user) throw new Error("User not found");
await user.revokePermission('access_admin_dashboard');
```
-By following these guidelines, you can efficiently manage and verify both team and user permissions within your application.
+## Direct vs. inherited permissions
+
+A permission can be present in two ways:
+
+- **Direct** - The user was explicitly granted that permission.
+- **Inherited** - The user was granted a permission that contains it, directly or recursively.
+
+The dashboard definition tables show direct containment only. The SDK can return recursive or direct-only lists:
+
+```tsx
+// Includes inherited permissions
+const allPermissions = await user.listPermissions(team);
+
+// Direct assignments only
+const directPermissions = await user.listPermissions(team, { recursive: false });
+```
+
+For checks like `hasPermission` and `getPermission`, Stack resolves contained permissions recursively so roles work as expected.
diff --git a/docs-mintlify/guides/apps/teams/overview.mdx b/docs-mintlify/guides/apps/teams/overview.mdx
index b8d23370c9..afdf2f2fa0 100644
--- a/docs-mintlify/guides/apps/teams/overview.mdx
+++ b/docs-mintlify/guides/apps/teams/overview.mdx
@@ -4,6 +4,424 @@ description: "Manage teams and team members"
sidebarTitle: "Overview"
---
+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, organizations, or projects.
+
+The server can perform all operations on a team. Client-side team and membership actions are gated by team permissions, so users can only perform the actions they are allowed to perform.
+
+## Dashboard
+
+The Teams app adds two dashboard pages:
+
+- **Teams** - List, create, edit, inspect, and delete teams.
+- **Team Settings** - Configure how teams are created and which permissions are granted by default.
+
+### Teams page
+
+The **Teams** page shows:
+
+- **Create Team** button - Opens a dialog with a required **Display Name** field.
+- **KPI cards** - New active teams, daily active teams, returning team rate, and total teams.
+- **Teams table** - Infinite-scroll table with URL-synced state and a default sort by newest teams first.
+
+The teams table includes:
+
+- **ID** - Monospace team ID.
+- **Display Name** - Team display name.
+- **Created At** - Creation timestamp.
+- **Actions** - Row actions for team-specific workflows.
+
+If no teams exist yet, the page may show an alert pointing project owners to project-level team settings if they were actually trying to invite someone to the project owner team.
+
+### Team row actions
+
+Each team row has an action menu:
+
+- **View Members** - Opens the team detail page.
+- **Edit** - Opens the **Edit Team** dialog. The dialog shows the immutable team ID and lets you update **Display Name**.
+- **Create Checkout** - Opens a product selector for team-scoped payment products, creates a temporary checkout URL, and shows it in a dialog. The URL expires after 24 hours.
+- **Delete** - Opens a destructive confirmation dialog. The confirmation text is:
+
+```text
+I understand that this action cannot be undone and all the team members will be also removed from the team.
+```
+
+Deleting a team removes its memberships as well.
+
+
+ **Create Checkout** only works with products whose customer type is `team`. If the selected product does not exist, has the wrong customer type, is already granted, or the team customer cannot be found, the dashboard shows an error toast.
+
+
+### Team detail page
+
+Click a team row or **View Members** to open the team detail page. The header shows:
+
+- Team avatar
+- Editable display name
+- Team creation date
+
+The page has category tabs. Some tabs only appear when the related app is installed:
+
+- **Members** - Always available when Teams is enabled.
+- **Payments** - Appears when Payments is installed.
+- **Analytics** - Appears when Analytics is installed.
+- **Metadata** - Always available.
+- **Install apps** - Shortcut to the Apps page if you want to add related apps.
+
+The selected tab is synced to the URL using the `tab` query parameter.
+
+### Members tab
+
+The **Members** tab shows a team member table and an **Add a user** action.
+
+The **Add a user** dialog has two paths:
+
+- **Invite a new user** - Enter an email address and click **Invite**. The project must have at least one configured non-wildcard domain so the dashboard can build the team invitation callback URL. After a successful invite, the button changes to **Invited!**.
+- **Add an existing user** - Search existing users and click **Add**. Users who are already members show **Added** and cannot be added again.
+
+The member table includes:
+
+- **User** - Avatar and display name, linking to the user detail page.
+- **Email**
+- **User ID** - Shortened ID with a copy-to-clipboard button.
+- **Email Verified** - Hidden by default, available as a column.
+- **Last active** - Default sort column, newest first.
+- **Permissions** - Direct team permissions only, shown as badges.
+- **Actions** - **Edit permissions** and **Remove from team**.
+
+**Edit permissions** opens a nested permission checklist built from the project's team permission definitions. It grants checked permissions and revokes unchecked permissions on save. The table shows only direct permissions; inherited permissions still apply at runtime through RBAC. If the permission fetch fails for a row, the table shows **Failed to load** and disables **Edit permissions** until the table is reloaded.
+
+**Remove from team** opens a destructive confirmation dialog:
+
+```text
+I understand this will cause the user to lose access to the team.
+```
+
+### Payments tab
+
+The **Payments** tab summarizes team-scoped billing when the Payments app is installed. It shows:
+
+- **Active subscriptions**
+- **Products owned**
+- **Lifetime spend** or **Recent spend** if the transaction window is truncated
+- **Products & subscriptions** table with product, type, quantity, and granted date
+- **Transaction history** table with type, detail, date, amount, and status
+- **Item balances** for team-scoped payment items
+
+Metrics are computed from recent team transactions. If the team has more than the dashboard's transaction cap, the page shows that older history is excluded from the metric cards.
+
+### Analytics tab
+
+The **Analytics** tab summarizes activity for the team's members when Analytics is installed. It scopes activity by member user IDs and shows:
+
+- **Members**
+- **Active (7d)**
+- **Active (30d)**
+- **Total events**
+- **Active users by hour of week** heatmap
+- **Daily activity** chart
+- **Top contributors** table
+
+If the team has no members or no activity, the charts show empty states. If analytics queries fail, the tab shows an **Analytics unavailable** card.
+
+### Metadata tab
+
+The **Metadata** tab lets you inspect and edit team metadata:
+
+- **Client metadata** - Readable and writable from client and server SDKs.
+- **Client read-only metadata** - Readable from client and server SDKs, writable from the server and dashboard.
+- **Server metadata** - Server-only metadata, editable from the dashboard.
+
+Use metadata for application-specific team data that belongs on the team object, such as billing identifiers, onboarding state, or workspace settings.
+
+### Team Settings page
+
+The **Team Settings** page controls team creation and default permissions.
+
+#### Team Creation
+
+The **Team Creation** card has two switches with deferred save/discard controls:
+
+- **Client Team Creation** - Controls whether users can create teams from account settings and the team switcher. This must be enabled before client-side `user.createTeam()` can be used.
+- **Personal Team on Sign-up** - Creates a personal team for each new user at sign-up. This does not affect existing users.
+
+Changes are marked as modified until you click **Save** or **Discard**.
+
+#### Default permissions
+
+Two cards control permissions that are automatically granted:
+
+- **Team Creator Default Permissions** - Granted to the user who creates a team.
+- **Team Member Default Permissions** - Granted to users when they join a team.
+
+Each card shows the selected permissions as badges, or **No default permissions set**. Click **Edit** to open a nested permission checklist. Inherited permissions are labeled with `from ` so you can see when a selected permission includes another permission indirectly.
+
+Default permissions are based on the team permission definitions from [RBAC](/guides/apps/rbac/overview).
+
+## 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 an action. Learn more about permissions [here](../rbac/overview).
+
+Here is an example of how to check if a user has a specific permission on the client:
+
+```tsx
+const user = useUser({ or: "redirect" });
+const team = user.useTeam("some-team-id");
+
+if (!team) {
+ return
+
+ ```tsx
+ "use client";
+ import { useUser } from "@stackframe/stack";
+
+ export function TeamList() {
+ const user = useUser({ or: "redirect" });
+ const allTeams = user.useTeams();
+ const someTeam = user.useTeam("some-team-id");
+
+ return (
+ <>
+
+
+ ```tsx
+ import { stackServerApp } from "@/stack/server";
+
+ export default async function TeamList() {
+ const user = await stackServerApp.getUser({ or: "redirect" });
+ const allTeams = await user.listTeams();
+ const someTeam = await user.getTeam("some-team-id");
+
+ return (
+ <>
+
+
+
+## Creating a team
+
+To create a team for the current user, use `createTeam` on the `User` object. The user is added to the team with the default team creator permissions configured in **Team Settings**.
+
+On the client, this requires **Client Team Creation** to be enabled in **Team Settings**.
+
+```tsx
+const team = await user.createTeam({
+ displayName: "New Team",
+});
+```
+
+To create a team on the server without adding a specific user, use `createTeam` on the server app:
+
+```tsx
+const team = await stackServerApp.createTeam({
+ displayName: "New Team",
+});
+```
+
+## Updating a team
+
+You can update a team with `update` on the `Team` object. On the client, the user must have the `$update_team` permission.
+
+```tsx
+await team.update({
+ displayName: "New Name",
+});
+```
+
+## 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.
+
+```tsx
+await team.update({
+ clientMetadata: {
+ customField: "value",
+ },
+});
+
+console.log(team.clientMetadata.customField); // "value"
+```
+
+## Listing users in a team
+
+You can list all users in a team with `listUsers` or `useUsers` on the `Team` object. To show a user's team profile, read `user.teamProfile`.
+
+On the client, the current user must have the `$read_members` permission.
+
+
+
+ ```tsx
+ // ... retrieve the team and ensure user has the necessary permissions
+ const users = team.useUsers();
+
+ return (
+
+
+ ```tsx
+ // ... retrieve the team
+ const users = await team.listUsers();
+
+ return (
+
+
+
+## Current user's team profile
+
+You can get the current user's team profile with `getTeamProfile` or `useTeamProfile` on the `User` object.
+
+
+
+ ```tsx
+ const teamProfile = user.useTeamProfile(team);
+ ```
+
+
+ ```tsx
+ const teamProfile = await user.getTeamProfile(team);
+ ```
+
+
+
+## Inviting users
+
+You can invite a user to a team with `inviteUser` on the `Team` object. The user receives an email with a link to join the team.
+
+On the client, the current user must have the `$invite_members` permission.
+
+```tsx
+await team.inviteUser({
+ email: "person@example.com",
+});
+```
+
+If you need to specify where the invitation returns after acceptance, pass an object with `email` and `callbackUrl`:
+
+```tsx
+await team.inviteUser({
+ email: "person@example.com",
+ callbackUrl: "https://example.com/team-invitation",
+});
+```
+
+## Adding a user directly
+
+If you want to add a user to a team without sending an email, use `addUser` on the server-side `Team` object.
+
+```tsx
+await team.addUser(user.id);
+```
+
+New members receive the default team member permissions configured in **Team Settings**.
+
+## Removing a user from a team
+
+You can remove a user from a team with `removeUser` on the `Team` object. On the client, the current user must have the `$remove_members` permission.
+
+```tsx
+await team.removeUser(user.id);
+```
+
+## Leaving a team
+
+All users can leave a team without any permissions required.
+
+```tsx
+const team = await user.getTeam("some-team-id");
+if (!team) throw new Error("Team not found");
+
+await user.leaveTeam(team);
+```
+
+## Deleting a team
+
+You can delete a team with `delete` on the `Team` object. On the client, the current user must have the `$delete_team` permission.
+
+```tsx
+await team.delete();
+```
+
+Deleting a team removes all memberships for that team. Make sure your app treats deleted team IDs as invalid and refreshes any team switchers after deletion.
+---
+title: "Teams"
+description: "Manage teams and team members"
+sidebarTitle: "Overview"
+---
+
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.
diff --git a/docs-mintlify/guides/apps/teams/team-selection.mdx b/docs-mintlify/guides/apps/teams/team-selection.mdx
index e77d17582c..129fd279e1 100644
--- a/docs-mintlify/guides/apps/teams/team-selection.mdx
+++ b/docs-mintlify/guides/apps/teams/team-selection.mdx
@@ -25,32 +25,36 @@ To facilitate team selection, Stack provides a component that looks like this:
-You can import and use the `SelectedTeamSwitcher` component for the "current team" method. It updates the `selectedTeam` when a user selects a team:
+You can import and use the `SelectedTeamSwitcher` component for the "current team" method. Pass the user's current `selectedTeam` so the switcher shows the saved selection on first render. When a user selects a different team, the switcher calls `user.setSelectedTeam()`:
-```jsx
-import { SelectedTeamSwitcher } from "@stackframe/stack";
+```tsx
+"use client";
+
+import { SelectedTeamSwitcher, useUser } from "@stackframe/stack";
export function MyPage() {
+ const user = useUser({ or: "redirect" });
+
return (
`/team/${team.id}`}
selectedTeam={team}
/>
```
-To implement the "deep link" + "default team" method, where you update the `selectedTeam` only when the user clicks "set to default team" or similar, pass `noUpdateSelectedTeam`:
+To implement the "deep link" + "default team" method, where changing pages should not update the user's saved selected team, pass `noUpdateSelectedTeam`:
-```jsx
+```tsx
`/team/${team.id}`}
selectedTeam={team}
@@ -58,17 +62,26 @@ To implement the "deep link" + "default team" method, where you update the `sele
/>
```
+Other useful options:
+
+- `allowNull` - Allows the user to select "no team".
+- `nullLabel` - Custom label for the null option.
+- `onChange` - Called whenever a team is selected.
+- `triggerClassName` - Adds classes to the switcher trigger.
+
## Example: Deep Link + Most Recent Team
-First, create a page at `/app/team/[teamId]/page.tsx` to display information about a specific team:
+First, create a client page at `app/team/[teamId]/page.tsx` to display information about a specific team:
-```jsx
+```tsx
"use client";
import { useUser, SelectedTeamSwitcher } from "@stackframe/stack";
+import { useParams } from "next/navigation";
-export default function TeamPage({ params }: { params: { teamId: string } }) {
- const user = useUser({ or: 'redirect' });
+export default function TeamPage() {
+ const user = useUser({ or: "redirect" });
+ const params = useParams<{ teamId: string }>();
const team = user.useTeam(params.teamId);
if (!team) {
@@ -89,26 +102,27 @@ export default function TeamPage({ params }: { params: { teamId: string } }) {
}
```
-Next, create a page to display all teams at `/app/team/page.tsx`:
+Next, create a page to display all teams at `app/team/page.tsx`:
-```jsx
+```tsx
"use client";
import { useRouter } from "next/navigation";
import { useUser } from "@stackframe/stack";
export default function TeamsPage() {
- const user = useUser({ or: 'redirect' });
+ const user = useUser({ or: "redirect" });
const teams = user.useTeams();
const router = useRouter();
const selectedTeam = user.selectedTeam;
return (
Team not found
;
+}
+
+const hasPermission = user.usePermission(team, "$invite_members");
+
+if (!hasPermission) {
+ return No permission
;
+}
+
+// Perform corresponding action like inviting a user
+```
+
+Always enforce authorization on the server for business logic:
+
+```tsx
+const user = await stackServerApp.getUser({ or: "redirect" });
+const team = await user.getTeam("some-team-id");
+
+if (!team || !(await user.hasPermission(team, "$invite_members"))) {
+ return new Response("Forbidden", { status: 403 });
+}
+```
+
+### Team profile
+
+A user can have a different profile for each team they belong to. This is separate from the user's personal profile. The team profile contains information like `displayName` and `profileImageUrl`. The team profile can be left empty and will automatically fall back to the user's personal profile information.
+
+The team profile is visible to 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 `listTeams` or `useTeams`, or fetch a specific team with `getTeam` or `useTeam`. These functions work on both clients and servers.
+
+
+ {allTeams.map(team => (
+
+ {team.displayName}
+ ))}
+
+ {someTeam ? someTeam.displayName : "Not a member of this team"}
+
+
+ );
+ }
+ ```
+
+ {allTeams.map(team => (
+
+ {team.displayName}
+ ))}
+
+ {someTeam ? someTeam.displayName : "Not a member of this team"}
+
+
+ );
+ }
+ ```
+
+ {users.map(user => (
+
+ );
+ ```
+ {user.teamProfile.displayName}
+ ))}
+
+ {users.map(user => (
+
+ );
+ ```
+ {user.teamProfile.displayName}
+ ))}
+
-You can import and use the `SelectedTeamSwitcher` component for the "current team" method. It updates the `selectedTeam` when a user selects a team:
+You can import and use the `SelectedTeamSwitcher` component for the "current team" method. Pass the user's current `selectedTeam` so the switcher shows the saved selection on first render. When a user selects a different team, the switcher calls `user.setSelectedTeam()`:
-```jsx
-import { SelectedTeamSwitcher } from "@stackframe/stack";
+```tsx
+"use client";
+
+import { SelectedTeamSwitcher, useUser } from "@stackframe/stack";
export function MyPage() {
+ const user = useUser({ or: "redirect" });
+
return (
-
);
}
```
-To combine the switcher with the deep link method, you can pass in `urlMap` and `selectedTeam`. The `urlMap` is a function to generate a URL based on the team information, and `selectedTeam` is the team that the user is currently working on. This lets you implement "deep link" + "most recent team". The component will update the `user.selectedTeam` with the `selectedTeam` prop:
+To combine the switcher with the deep link method, pass both `urlMap` and `selectedTeam`. The `urlMap` function generates a URL for each team, and `selectedTeam` is the team for the current page. This implements "deep link" + "most recent team": selecting a team navigates to that team's URL, and the component updates `user.selectedTeam` unless you disable that behavior.
-```jsx
+```tsx
- {selectedTeam &&
+ {selectedTeam && (
}
+
+ )}
{
+ console.log(team ? `Selected ${team.id}` : "Selected personal scope");
+ }}
+ />
+ );
+}
+```
+
+When `allowNull` is enabled, the `onChange` callback can receive `null`. If `noUpdateSelectedTeam` is not set, selecting a real team updates `user.selectedTeam`; selecting the null option clears it.
diff --git a/docs-mintlify/guides/apps/webhooks/overview.mdx b/docs-mintlify/guides/apps/webhooks/overview.mdx
index 4a61ff22b7..b04d144aac 100644
--- a/docs-mintlify/guides/apps/webhooks/overview.mdx
+++ b/docs-mintlify/guides/apps/webhooks/overview.mdx
@@ -6,7 +6,7 @@ icon: "/images/app-icons/webhooks.svg"
Webhooks are a powerful way to keep your backend in sync with Stack. They allow you to receive real-time updates when events occur in your Stack project, such as when a user or team is created, updated, or deleted.
-For payload schemas and each webhook event, see the [webhook API reference](/api/webhooks/users/usercreated).
+For payload schemas and generated webhook event references, see the [webhook API reference](/api/webhooks/users/usercreated).
## Setting up webhooks
@@ -18,11 +18,94 @@ In the Stack dashboard, you can create a webhook endpoint in the "Webhooks" sect
"data": {
"id": "2209422a-eef7-4668-967d-be79409972c5",
"display_name": "My Team",
- ...
+ "profile_image_url": null,
+ "client_metadata": {},
+ "client_read_only_metadata": {},
+ "server_metadata": {},
+ "created_at_millis": 1715360400000
}
}
```
+## Dashboard
+
+The **Webhooks** dashboard page embeds the endpoint manager where you create endpoints, send test events, inspect delivery history, and copy the verification secret for each endpoint.
+
+
+ Webhooks are unavailable in preview mode. Preview deployments show an informational alert instead of the endpoint manager.
+
+
+### Endpoints list
+
+The main Webhooks page shows your webhook endpoints. Each endpoint includes:
+
+- **Endpoint URL** - The URL Stack sends events to.
+- **Description** - Optional label for your own reference.
+- **Status** - **Active** or **Disabled**.
+- **Actions** - View details, test, edit, or delete the endpoint.
+
+Use this list to find existing endpoints, open endpoint details, or start endpoint actions.
+
+### Creating an endpoint
+
+Click **Add new endpoint** to open the endpoint creation dialog. The dialog includes:
+
+- **URL** - Required, must be a valid URL.
+- **Description** - Optional, useful for labeling environments like `Production`, `Staging`, or `Local tunnel`.
+
+The dialog warns you to use only URLs you control because webhook payloads can contain sensitive user and team data. If the URL starts with `http://`, the dashboard shows an additional warning:
+
+```text
+Using HTTP endpoints is insecure. This can expose your user data to attackers. Only use HTTP endpoints in development environments.
+```
+
+After creation, the dashboard shows a success state with the endpoint URL and description, plus a **Test endpoint** button so you can immediately send a test event.
+
+### Testing an endpoint
+
+Endpoint rows have a **Test** action, and newly-created endpoints can be tested from the success state. The test dialog sends a `stack.test` event to the selected endpoint and shows the sample payload before sending:
+
+```json
+{
+ "type": "stack.test",
+ "data": {
+ "message": "Stack webhook test event triggered from the Stack dashboard.",
+ "endpointUrl": "https://example.com/api/webhooks/stack"
+ }
+}
+```
+
+Click **Send test event** to send it. On success, the dashboard confirms that the event was sent and the endpoint is ready. On failure, it shows the delivery error returned by the webhook service.
+
+### Editing and deleting endpoints
+
+The endpoint action menu includes:
+
+- **View Details** - Opens the endpoint detail page.
+- **Test** - Opens the test-event dialog.
+- **Edit** - Lets you update the endpoint description. The endpoint URL is not edited in this dialog.
+- **Delete** - Opens a destructive confirmation dialog. Deleted endpoints stop receiving events.
+
+### Endpoint details
+
+The endpoint detail page shows:
+
+- **URL** - The endpoint URL.
+- **Description** - The saved description, or `-` when empty.
+- **Verification Secret** - The endpoint signing secret, with a copy button.
+
+Use the verification secret as `STACK_WEBHOOK_SECRET` (or your own secret environment variable name) in your webhook receiver. Do not expose it to the browser.
+
+### Event history
+
+The endpoint detail page also shows recent message attempts for that endpoint with:
+
+- **ID** - Message attempt ID.
+- **Status** - **Success**, **Pending**, **Fail**, **Sending**, or **Unknown**.
+- **Timestamp** - When the attempt was created.
+
+Use the event history to confirm whether deliveries succeeded, are pending, or failed. If no events have been sent yet, the dashboard shows **No events sent yet.**
+
## Testing webhooks locally
You can use services like [Svix Playground](https://www.svix.com/play/) or [Webhook.site](https://webhook.site/) to test the receiving of webhooks or relay them to your local development environment.
@@ -184,10 +267,13 @@ def stack_webhook(request):
```
```python FastAPI
+import os
+
from fastapi import FastAPI, Request
from svix.webhooks import Webhook
app = FastAPI()
+STACK_WEBHOOK_SECRET = os.environ["STACK_WEBHOOK_SECRET"]
@app.post("/api/webhooks/stack")
@@ -207,10 +293,13 @@ async def stack_webhook(request: Request):
```
```python Flask
+import os
+
from flask import Flask, jsonify, request
from svix.webhooks import Webhook
app = Flask(__name__)
+STACK_WEBHOOK_SECRET = os.environ["STACK_WEBHOOK_SECRET"]
@app.post("/api/webhooks/stack")
@@ -233,11 +322,13 @@ If you do not want to install the Svix client library or are using a language th
## Event types
-These are the `type` values you may receive. Each links to its API reference page.
+These are the `type` values you may receive. Linked events include generated API reference pages with their payload schemas.
- [`user.created`](/api/webhooks/users/usercreated)
- [`user.updated`](/api/webhooks/users/userupdated)
- [`user.deleted`](/api/webhooks/users/userdeleted)
+- `project_permission.created` - Triggered when a project-level permission is granted to a user. The payload includes `id` and `user_id`.
+- `project_permission.deleted` - Triggered when a project-level permission is revoked from a user. The payload includes `id` and `user_id`.
- [`team.created`](/api/webhooks/teams/teamcreated)
- [`team.updated`](/api/webhooks/teams/teamupdated)
- [`team.deleted`](/api/webhooks/teams/teamdeleted)
@@ -248,4 +339,4 @@ These are the `type` values you may receive. Each links to its API reference pag
## Examples
-Some members of the community have shared their webhook implementations. For example, [here is an example by Clark Gredona](https://gist.github.com/clarkg/56ffad44949826ae3efe0a431b6021c4) that validates the Webhook schema and update a database user.
+Some members of the community have shared their webhook implementations. For example, [here is an example by Clark Gredona](https://gist.github.com/clarkg/56ffad44949826ae3efe0a431b6021c4) that validates the webhook schema and updates a database user.
diff --git a/docs-mintlify/snippets/docs-apps-home-grid.jsx b/docs-mintlify/snippets/docs-apps-home-grid.jsx
index 2339423c91..7ae4e8bc28 100644
--- a/docs-mintlify/snippets/docs-apps-home-grid.jsx
+++ b/docs-mintlify/snippets/docs-apps-home-grid.jsx
@@ -21,7 +21,7 @@ export const DocsAppsHomeGrid = () => {
{ name: "Payments", href: "/guides/apps/payments/overview", iconSrc: "/images/app-icons/payments.svg" },
{ name: "Analytics", href: "/guides/apps/analytics/overview", iconSrc: "/images/app-icons/analytics.svg" },
{ name: "Teams", href: "/guides/apps/teams/overview", iconSrc: "/images/app-icons/teams.svg" },
- { name: "Fraud Protection", href: "/guides/apps/fraud-protection/overview", iconSrc: "/images/app-icons/fraud-protection.svg" },
+ { name: "Fraud Protection", href: "/guides/apps/authentication/fraud-protection", iconSrc: "/images/app-icons/fraud-protection.svg" },
{ name: "RBAC", href: "/guides/apps/rbac/overview", iconSrc: "/images/app-icons/rbac.svg" },
{ name: "API Keys", href: "/guides/apps/api-keys/overview", iconSrc: "/images/app-icons/api-keys.svg" },
{ name: "Data Vault", href: "/guides/apps/data-vault/overview", iconSrc: "/images/app-icons/data-vault.svg" },