From 1da99a4c3119856c1e8844ca018285526795c708 Mon Sep 17 00:00:00 2001
From: CactusBlue <thecactusblue@gmail.com>
Date: Wed, 26 Mar 2025 04:54:46 -0700
Subject: [PATCH] User permission docs (#575)

<!-- ELLIPSIS_HIDDEN -->



> [!IMPORTANT]
> Adds documentation for user permissions in `permissions.mdx`,
detailing creation, checking, listing, granting, and revoking, with
client and server examples.
>
>   - **Documentation**:
> - Adds `Permission Types` section in `permissions.mdx`, explaining
`Team Permissions` and `User Permissions`.
> - Details on creating, checking, listing, granting, and revoking `User
Permissions`.
> - Provides code examples for client and server components using
`getUserPermission`, `useUserPermission`, `listUserPermissions`,
`grantUserPermission`, and `revokeUserPermission`.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 2bff5f99bff4ac57ca9b571864c3aa10db0877d8. It will automatically
update as commits are pushed.</sup>

<!-- ELLIPSIS_HIDDEN -->
---
 .../pages-template/concepts/permissions.mdx   | 125 +++++++++++++++++-
 1 file changed, 124 insertions(+), 1 deletion(-)

diff --git a/docs/fern/docs/pages-template/concepts/permissions.mdx b/docs/fern/docs/pages-template/concepts/permissions.mdx
index 427a0d2a7..6a15eacfb 100644
--- a/docs/fern/docs/pages-template/concepts/permissions.mdx
+++ b/docs/fern/docs/pages-template/concepts/permissions.mdx
@@ -3,6 +3,15 @@ slug: concepts/permissions
 subtitle: Control what each user can do and access with the permission system
 ---
 
+## Permission Types
+
+Stack supports two types of permissions:
+
+1. **Team Permissions**: Control what a user can do within a specific team
+2. **User Permissions**: Control what a user can do globally, across the entire project
+
+Both permission types can be managed from the dashboard, and both support arbitrary nesting.
+
 ## Team Permissions
 
 Team permissions control what a user can do within each team. You can create and assign permissions to team members from the Stack dashboard. These permissions could include actions like `create_post` or `read_secret_info`, or roles like `admin` or `moderator`. Within your app, you can verify if a user has a specific permission within a team.
@@ -127,4 +136,118 @@ const user = await stackServerApp.getUser();
 await user.revokePermission(team, 'read');
 ```
 
-By following these guidelines, you can efficiently manage and verify team permissions within your application.
\ No newline at end of file
+## User Permissions
+
+User permissions are global permissions that apply to a user across the entire project, regardless of team context. These permissions are useful for handling things like premium plan subscriptions or global admin access.
+
+### Creating a User Permission
+
+To create a new user permission, navigate to the `User 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.
+
+### Checking if a User has a User Permission
+
+To check whether a user has a specific user permission, use the `getUserPermission` method or the `useUserPermission` hook. Here's an example:
+
+<Tabs>
+  <Tab title="Client Component">
+    
+    ```tsx title="Check user permission on the client"
+    "use client";
+    import { useUser } from "@stackframe/stack";
+
+    export function CheckGlobalPermission() {
+      const user = useUser({ or: 'redirect' });
+      const permission = user.useUserPermission('access_admin_dashboard');
+
+      return (
+        <div>
+          {permission ? 'You can access the admin dashboard' : 'Access denied'}
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab title="Server Component">
+    
+    ```tsx title="Check user permission on the server"
+    import { stackServerApp } from "@/stack";
+
+    export default async function CheckGlobalPermission() {
+      const user = await stackServerApp.getUser({ or: 'redirect' });
+      const permission = await user.getUserPermission('access_admin_dashboard');
+
+      return (
+        <div>
+          {permission ? 'You can access the admin dashboard' : 'Access denied'}
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Listing All User Permissions
+
+To get a list of all global permissions a user has, use the `listUserPermissions` method or the `useUserPermissions` hook:
+
+<Tabs>
+  <Tab title="Client Component" default>
+
+    ```tsx title="List global permissions on the client"
+    "use client";
+    import { useUser } from "@stackframe/stack";
+
+    export function DisplayGlobalPermissions() {
+      const user = useUser({ or: 'redirect' });
+      const permissions = user.useUserPermissions();
+
+      return (
+        <div>
+          {permissions.map(permission => (
+            <div key={permission.id}>{permission.id}</div>
+          ))}
+        </div>
+      );
+    }
+    ```
+  </Tab>
+  <Tab title="Server Component">
+
+    ```tsx title="List global permissions on the server"
+    import { stackServerApp } from "@/stack";
+
+    export default async function DisplayGlobalPermissions() {
+      const user = await stackServerApp.getUser({ or: 'redirect' });
+      const permissions = await user.listUserPermissions();
+
+      return (
+        <div>
+          {permissions.map(permission => (
+            <div key={permission.id}>{permission.id}</div>
+          ))}
+        </div>
+      );
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Granting a User Permission
+
+To grant a global permission to a user, use the `grantUserPermission` method:
+
+```tsx
+const user = await stackServerApp.getUser();
+await user.grantUserPermission('access_admin_dashboard');
+```
+
+### Revoking a User Permission
+
+To revoke a global permission from a user, use the `revokeUserPermission` method:
+
+```tsx
+const user = await stackServerApp.getUser();
+await user.revokeUserPermission('access_admin_dashboard');
+```
+
+By following these guidelines, you can efficiently manage and verify both team and user permissions within your application.