From d566e9803daab01182a7a3d28c26973d48dcb01e Mon Sep 17 00:00:00 2001
From: Madison <madison.w.kennedy@gmail.com>
Date: Tue, 8 Jul 2025 20:09:55 -0500
Subject: [PATCH] python docs changes.

---
 docs/docs-platform.yml                        |  50 +-
 docs/src/components/layouts/shared-header.tsx |   2 +-
 .../templates-python/authentication/index.mdx |  30 -
 .../templates-python/authentication/meta.json |  11 -
 .../concepts/teams-management.mdx             | 599 ++++++++++++++++++
 .../user-authentication.mdx                   |   8 -
 .../getting-started/setup.mdx                 | 189 +++---
 docs/templates-python/integration/django.mdx  |   6 -
 docs/templates-python/integration/meta.json   |  10 -
 docs/templates-python/meta.json               |  22 +-
 .../team-management/meta.json                 |  10 -
 .../user-management/meta.json                 |  10 -
 12 files changed, 705 insertions(+), 242 deletions(-)
 delete mode 100644 docs/templates-python/authentication/index.mdx
 delete mode 100644 docs/templates-python/authentication/meta.json
 create mode 100644 docs/templates-python/concepts/teams-management.mdx
 rename docs/templates-python/{authentication => concepts}/user-authentication.mdx (96%)
 delete mode 100644 docs/templates-python/integration/django.mdx
 delete mode 100644 docs/templates-python/integration/meta.json
 delete mode 100644 docs/templates-python/team-management/meta.json
 delete mode 100644 docs/templates-python/user-management/meta.json

diff --git a/docs/docs-platform.yml b/docs/docs-platform.yml
index 05cd9bb1c..6e01a0afb 100644
--- a/docs/docs-platform.yml
+++ b/docs/docs-platform.yml
@@ -261,54 +261,12 @@ pages:
 
   # Python-specific content from templates-python/
   # Authentication section
-  - path: authentication/api-setup.mdx
-    platforms: ["python"]
   
-  - path: authentication/user-sessions.mdx
-    platforms: ["python"]
+  - path: concepts/user-authentication.mdx
+    platforms: ["python"] # python only
   
-  - path: authentication/oauth-flows.mdx
-    platforms: ["python"]
-  
-  - path: authentication/server-validation.mdx
-    platforms: ["python"]
+  - path: concepts/teams-management.mdx
+    platforms: ["python"] # python only
 
-  # User Management section
-  - path: user-management/create-users.mdx
-    platforms: ["python"]
   
-  - path: user-management/user-operations.mdx
-    platforms: ["python"]
-  
-  - path: user-management/custom-user-data.mdx
-    platforms: ["python"]
-  
-  - path: user-management/user-permissions.mdx
-    platforms: ["python"]
-
-  # Team Management section
-  - path: team-management/team-operations.mdx
-    platforms: ["python"]
-  
-  - path: team-management/team-invitations.mdx
-    platforms: ["python"]
-  
-  - path: team-management/team-permissions.mdx
-    platforms: ["python"]
-  
-  - path: team-management/organization-management.mdx
-    platforms: ["python"]
-
-  # Framework Integration section
-  - path: integration/django.mdx
-    platforms: ["python"]
-  
-  - path: integration/flask.mdx
-    platforms: ["python"]
-  
-  - path: integration/fastapi.mdx
-    platforms: ["python"]
-  
-  - path: integration/standalone-scripts.mdx
-    platforms: ["python"]
 
diff --git a/docs/src/components/layouts/shared-header.tsx b/docs/src/components/layouts/shared-header.tsx
index 442a8315b..085e227bd 100644
--- a/docs/src/components/layouts/shared-header.tsx
+++ b/docs/src/components/layouts/shared-header.tsx
@@ -80,7 +80,7 @@ function AIChatToggleButton() {
     return null;
   }
 
-  const { isChatOpen, toggleChat } = sidebarContext;
+  const { toggleChat } = sidebarContext;
 
   return (
     <button
diff --git a/docs/templates-python/authentication/index.mdx b/docs/templates-python/authentication/index.mdx
deleted file mode 100644
index 13ba63c49..000000000
--- a/docs/templates-python/authentication/index.mdx
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: "Authentication Flows"
-description: "Learn how to implement authentication flows in your Python application using Stack Auth's REST API"
----
-This section covers the core authentication patterns and flows you'll need to implement secure authentication in your Python application using Stack Auth's REST API.
-
-<CardGroup cols={2}>
-  <Card 
-    title="User Authentication"
-    href="./authentication/user-authentication"
-    icon="user"
-  >
-    Set up your Python client and configure API credentials for Stack Auth integration.
-  </Card>
-</CardGroup>
-
-## Authentication Patterns
-
-Each authentication flow addresses specific use cases:
-
-- **API Setup**: Foundation for all authentication operations
-- **User Sessions**: Managing authenticated user state and session lifecycle  
-- **OAuth Flows**: Social login integration (Google, GitHub, etc.)
-- **Server Validation**: Securing your API endpoints and validating requests
-
-## Getting Started
-
-Start with [API Setup & Configuration](./api-setup) to establish your Python client, then proceed to the specific authentication flow that matches your application's needs.
-
-For framework-specific integration examples, see the [Framework Integration](../integration) section.
diff --git a/docs/templates-python/authentication/meta.json b/docs/templates-python/authentication/meta.json
deleted file mode 100644
index 94a4af185..000000000
--- a/docs/templates-python/authentication/meta.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "title": "Authentication",
-  "description": "Authentication flows and patterns for Python applications",
-  "pages": [
-    "index",
-    "api-setup",
-    "user-sessions",
-    "oauth-flows",
-    "server-validation"
-  ]
-} 
diff --git a/docs/templates-python/concepts/teams-management.mdx b/docs/templates-python/concepts/teams-management.mdx
new file mode 100644
index 000000000..1f1768625
--- /dev/null
+++ b/docs/templates-python/concepts/teams-management.mdx
@@ -0,0 +1,599 @@
+---
+title: "Teams Management"
+description: "Learn how to implement team functionality in your Python application using Stack Auth's REST API"
+---
+
+After setting up your [Stack Auth helper function](../getting-started/setup.mdx), you can implement comprehensive team functionality in your Python application.
+
+## Team Management
+
+Stack Auth provides full team management capabilities including:
+- **Team Creation & Management** - Create and update teams with metadata
+- **Team Memberships** - Add and remove users from teams  
+- **Team Invitations** - Send email invitations to join teams
+- **Team Permissions** - Control what team members can do
+- **Team Profiles** - Manage user profiles within team context
+
+### Creating a Team
+
+To create a new team:
+
+```python
+def create_team(access_token, display_name, creator_user_id=None):
+    """
+    Create a new team
+    Returns the created team data
+    """
+    body = {
+        'display_name': display_name
+    }
+    
+    # Optionally specify a creator (only on server)
+    if creator_user_id:
+        body['creator_user_id'] = creator_user_id
+    
+    response = stack_auth_request('POST', 'api/v1/teams', 
+        headers={'x-stack-access-token': access_token},
+        json=body
+    )
+    
+    return {
+        'id': response['id'],
+        'display_name': response['display_name'],
+        'profile_image_url': response['profile_image_url'],
+        'client_metadata': response['client_metadata'],
+        'client_read_only_metadata': response['client_read_only_metadata'],
+        'created_at_millis': response.get('created_at_millis')  # Server only
+    }
+
+# Example usage
+team_data = create_team(
+    access_token=access_token,
+    display_name="Engineering Team"
+)
+team_id = team_data['id']
+print(f"Created team: {team_data['display_name']}")
+```
+
+### Listing Teams
+
+Get all teams for the current user:
+
+```python
+def list_user_teams(access_token):
+    """
+    List all teams that the current user is a member of
+    """
+    response = stack_auth_request('GET', 'api/v1/teams?user_id=me',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return response['items']
+
+def list_all_teams():
+    """
+    List all teams in the project (server access only)
+    """
+    response = stack_auth_request('GET', 'api/v1/teams')
+    return response['items']
+
+# Example usage
+user_teams = list_user_teams(access_token)
+print(f"User is member of {len(user_teams)} teams")
+
+# Server-side: list all teams
+all_teams = list_all_teams()
+print(f"Total teams in project: {len(all_teams)}")
+```
+
+### Getting Team Information
+
+Retrieve details about a specific team:
+
+```python
+def get_team(access_token, team_id):
+    """
+    Get information about a specific team
+    """
+    response = stack_auth_request('GET', f'api/v1/teams/{team_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return {
+        'id': response['id'],
+        'display_name': response['display_name'],
+        'profile_image_url': response['profile_image_url'],
+        'client_metadata': response['client_metadata'],
+        'client_read_only_metadata': response['client_read_only_metadata']
+    }
+
+# Example usage
+team_info = get_team(access_token, team_id)
+print(f"Team: {team_info['display_name']}")
+```
+
+### Updating Team Information
+
+Update team details (requires `$update_team` permission):
+
+```python
+def update_team(access_token, team_id, **updates):
+    """
+    Update team information
+    Requires $update_team permission
+    """
+    # Filter out None values
+    body = {k: v for k, v in updates.items() if v is not None}
+    
+    response = stack_auth_request('PATCH', f'api/v1/teams/{team_id}',
+        headers={'x-stack-access-token': access_token},
+        json=body
+    )
+    
+    return response
+
+# Example usage
+updated_team = update_team(
+    access_token=access_token,
+    team_id=team_id,
+    display_name="Updated Engineering Team",
+    profile_image_url="https://example.com/team-logo.png",
+    client_metadata={
+        "department": "Engineering",
+        "location": "San Francisco"
+    }
+)
+```
+
+## Team Membership Management
+
+### Adding Members to a Team
+
+Add users to a team (server access required):
+
+```python
+def add_team_member(team_id, user_id):
+    """
+    Add a user to a team (server access only)
+    """
+    response = stack_auth_request('POST', f'api/v1/team-memberships/{team_id}/{user_id}',
+        json={}
+    )
+    return response
+
+# Example usage
+add_team_member(team_id, user_id)
+print(f"Added user {user_id} to team {team_id}")
+```
+
+### Removing Members from a Team
+
+Remove users from a team (requires `$remove_members` permission):
+
+```python
+def remove_team_member(access_token, team_id, user_id):
+    """
+    Remove a user from a team
+    Requires $remove_members permission
+    """
+    stack_auth_request('DELETE', f'api/v1/team-memberships/{team_id}/{user_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+
+# Example usage
+remove_team_member(access_token, team_id, user_id)
+print(f"Removed user {user_id} from team {team_id}")
+```
+
+### Getting Team Members
+
+List all members of a team:
+
+```python
+def get_team_members(access_token, team_id):
+    """
+    Get all members of a team with their profiles
+    Requires $read_members permission
+    """
+    response = stack_auth_request('GET', f'api/v1/team-member-profiles?team_id={team_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return response['items']
+
+# Example usage
+members = get_team_members(access_token, team_id)
+for member in members:
+    print(f"Member: {member['display_name']} ({member['user_id']})")
+```
+
+## Team Invitations
+
+### Sending Team Invitations
+
+Invite users to join a team via email:
+
+```python
+def send_team_invitation(access_token, team_id, email, callback_url):
+    """
+    Send an invitation to join a team
+    Requires $invite_members permission
+    """
+    response = stack_auth_request('POST', 'api/v1/team-invitations/send-code',
+        headers={'x-stack-access-token': access_token},
+        json={
+            'email': email,
+            'team_id': team_id,
+            'callback_url': callback_url
+        }
+    )
+    
+    return {
+        'success': response['success'],
+        'invitation_id': response['id']
+    }
+
+# Example usage
+invitation_result = send_team_invitation(
+    access_token=access_token,
+    team_id=team_id,
+    email="newmember@example.com",
+    callback_url="https://yourapp.com/join-team"
+)
+print(f"Invitation sent: {invitation_result['invitation_id']}")
+```
+
+### Accepting Team Invitations
+
+Complete the invitation process when a user clicks the invitation link:
+
+```python
+def accept_team_invitation(code):
+    """
+    Accept a team invitation using the code from the invitation email
+    """
+    response = stack_auth_request('POST', 'api/v1/team-invitations/accept',
+        json={'code': code}
+    )
+    
+    return response
+
+# Example usage (when user clicks invitation link)
+accept_team_invitation(invitation_code)
+print("User successfully joined the team!")
+```
+
+### Listing Team Invitations
+
+Get pending invitations for a team:
+
+```python
+def list_team_invitations(access_token, team_id):
+    """
+    List pending invitations for a team
+    Requires $invite_members permission
+    """
+    response = stack_auth_request('GET', f'api/v1/team-invitations?team_id={team_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return response['items']
+
+# Example usage
+invitations = list_team_invitations(access_token, team_id)
+for invitation in invitations:
+    print(f"Pending invitation for: {invitation['recipient_email']}")
+```
+
+## Team Permissions Management
+
+### Granting Team Permissions
+
+Give specific permissions to team members:
+
+```python
+def grant_team_permission(team_id, user_id, permission_id):
+    """
+    Grant a permission to a user in a team (server access only)
+    """
+    response = stack_auth_request('POST', f'api/v1/team-permissions/{team_id}/{user_id}/{permission_id}',
+        json={}
+    )
+    return response
+
+# Example usage
+grant_team_permission(team_id, user_id, "$update_team")
+grant_team_permission(team_id, user_id, "$invite_members")
+print(f"Granted permissions to user {user_id}")
+```
+
+### Revoking Team Permissions
+
+Remove permissions from team members:
+
+```python
+def revoke_team_permission(team_id, user_id, permission_id):
+    """
+    Revoke a permission from a user in a team (server access only)
+    """
+    stack_auth_request('DELETE', f'api/v1/team-permissions/{team_id}/{user_id}/{permission_id}')
+
+# Example usage
+revoke_team_permission(team_id, user_id, "$update_team")
+print(f"Revoked permission from user {user_id}")
+```
+
+### Checking Team Permissions
+
+Check if a user has specific permissions in a team:
+
+```python
+def check_team_permission(access_token, team_id, user_id, permission_id):
+    """
+    Check if a user has a specific permission in a team
+    """
+    try:
+        response = stack_auth_request('GET', f'api/v1/team-permissions/{team_id}/{user_id}/{permission_id}',
+            headers={'x-stack-access-token': access_token}
+        )
+        return True
+    except Exception as e:
+        if "TEAM_PERMISSION_NOT_FOUND" in str(e):
+            return False
+        raise e
+
+# Example usage
+can_update = check_team_permission(access_token, team_id, user_id, "$update_team")
+if can_update:
+    print("User can update the team")
+else:
+    print("User cannot update the team")
+```
+
+### Listing User Permissions
+
+Get all permissions a user has in a team:
+
+```python
+def list_user_team_permissions(access_token, team_id, user_id="me"):
+    """
+    List all permissions a user has in a team
+    """
+    response = stack_auth_request('GET', f'api/v1/team-permissions/{team_id}/{user_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return response['items']
+
+# Example usage
+permissions = list_user_team_permissions(access_token, team_id)
+permission_ids = [p['id'] for p in permissions]
+print(f"User permissions: {permission_ids}")
+```
+
+## Team Member Profiles
+
+### Managing Team Member Profiles
+
+Users can have different display names and profile information within each team:
+
+```python
+def update_team_member_profile(access_token, team_id, user_id="me", **profile_data):
+    """
+    Update a user's profile within a team context
+    """
+    response = stack_auth_request('PATCH', f'api/v1/team-member-profiles/{team_id}/{user_id}',
+        headers={'x-stack-access-token': access_token},
+        json=profile_data
+    )
+    
+    return response
+
+def get_team_member_profile(access_token, team_id, user_id="me"):
+    """
+    Get a user's profile within a team context
+    """
+    response = stack_auth_request('GET', f'api/v1/team-member-profiles/{team_id}/{user_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    
+    return response
+
+# Example usage
+# Update current user's profile in the team
+updated_profile = update_team_member_profile(
+    access_token=access_token,
+    team_id=team_id,
+    display_name="John Doe (Engineering Lead)",
+    profile_image_url="https://example.com/john-avatar.png"
+)
+
+# Get the updated profile
+profile = get_team_member_profile(access_token, team_id)
+print(f"Team profile: {profile['display_name']}")
+```
+
+### Deleting Teams
+
+Remove a team entirely (requires `$delete_team` permission):
+
+```python
+def delete_team(access_token, team_id):
+    """
+    Delete a team (requires $delete_team permission)
+    """
+    response = stack_auth_request('DELETE', f'api/v1/teams/{team_id}',
+        headers={'x-stack-access-token': access_token}
+    )
+    return response
+
+# Example usage
+delete_team(access_token, team_id)
+print(f"Team {team_id} deleted successfully")
+```
+
+## Complete Team Management Example
+
+Here's a comprehensive example that demonstrates a full team management workflow:
+
+```python
+import os
+import requests
+
+# Setup (from setup guide)
+stack_project_id = os.getenv("STACK_PROJECT_ID")
+stack_publishable_client_key = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
+stack_secret_server_key = os.getenv("STACK_SECRET_SERVER_KEY")
+
+def stack_auth_request(method, endpoint, **kwargs):
+    res = requests.request(
+        method,
+        f'https://api.stack-auth.com/{endpoint}',
+        headers={
+            'x-stack-access-type': 'server',  # or 'client' if you're only accessing the client API
+            'x-stack-project-id': stack_project_id,
+            'x-stack-publishable-client-key': stack_publishable_client_key,
+            'x-stack-secret-server-key': stack_secret_server_key,  # not necessary if access type is 'client'
+            **kwargs.pop('headers', {}),
+        },
+        **kwargs,
+    )
+    if res.status_code >= 400:
+        raise Exception(f"Stack Auth API request failed with {res.status_code}: {res.text}")
+    return res.json()
+
+class TeamManager:
+    def __init__(self, access_token):
+        self.access_token = access_token
+    
+    def create_and_setup_team(self, name, member_emails):
+        """Create a team and invite members"""
+        # Create the team
+        team = create_team(self.access_token, name)
+        team_id = team['id']
+        
+        print(f"Created team: {name} (ID: {team_id})")
+        
+        # Send invitations to members
+        invitation_results = []
+        for email in member_emails:
+            try:
+                result = send_team_invitation(
+                    self.access_token,
+                    team_id,
+                    email,
+                    "https://yourapp.com/join-team"
+                )
+                invitation_results.append((email, result['invitation_id']))
+                print(f"Invited {email}")
+            except Exception as e:
+                print(f"Failed to invite {email}: {e}")
+        
+        return team, invitation_results
+    
+    def manage_team_permissions(self, team_id, admin_user_ids):
+        """Grant admin permissions to specific users"""
+        admin_permissions = ["$update_team", "$invite_members", "$remove_members"]
+        
+        for user_id in admin_user_ids:
+            for permission in admin_permissions:
+                try:
+                    grant_team_permission(team_id, user_id, permission)
+                    print(f"Granted {permission} to {user_id}")
+                except Exception as e:
+                    print(f"Failed to grant {permission} to {user_id}: {e}")
+    
+    def get_team_overview(self, team_id):
+        """Get complete team information"""
+        # Get team details
+        team_info = get_team(self.access_token, team_id)
+        
+        # Get team members
+        try:
+            members = get_team_members(self.access_token, team_id)
+        except Exception:
+            members = []  # User might not have read_members permission
+        
+        # Get pending invitations
+        try:
+            invitations = list_team_invitations(self.access_token, team_id)
+        except Exception:
+            invitations = []  # User might not have invite_members permission
+        
+        return {
+            'team': team_info,
+            'members': members,
+            'pending_invitations': invitations
+        }
+
+# Example usage
+team_manager = TeamManager(access_token)
+
+# Create a new team with initial members
+team, invitations = team_manager.create_and_setup_team(
+    name="Product Team",
+    member_emails=["alice@example.com", "bob@example.com", "charlie@example.com"]
+)
+
+# Make some users team admins (server-side operation)
+admin_users = ["user-id-1", "user-id-2"]
+team_manager.manage_team_permissions(team['id'], admin_users)
+
+# Get team overview
+overview = team_manager.get_team_overview(team['id'])
+print(f"\nTeam Overview:")
+print(f"Name: {overview['team']['display_name']}")
+print(f"Members: {len(overview['members'])}")
+print(f"Pending Invitations: {len(overview['pending_invitations'])}")
+```
+
+## Error Handling
+
+Common team-related errors you might encounter:
+
+```python
+def handle_team_errors(func):
+    """Decorator to handle common team operation errors"""
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            error_message = str(e)
+            
+            if "TEAM_PERMISSION_REQUIRED" in error_message:
+                print("Insufficient permissions for this team operation")
+            elif "TEAM_MEMBERSHIP_NOT_FOUND" in error_message:
+                print("User is not a member of this team")
+            elif "TEAM_NOT_FOUND" in error_message:
+                print("Team not found")
+            elif "TEAM_MEMBERSHIP_ALREADY_EXISTS" in error_message:
+                print("User is already a member of this team")
+            elif "USER_NOT_FOUND" in error_message:
+                print("User not found")
+            else:
+                print(f"Team operation error: {error_message}")
+            
+            raise e
+    return wrapper
+
+@handle_team_errors
+def safe_add_member(team_id, user_id):
+    return add_team_member(team_id, user_id)
+
+@handle_team_errors
+def safe_send_invitation(access_token, team_id, email, callback_url):
+    return send_team_invitation(access_token, team_id, email, callback_url)
+```
+
+## Common Team Permission IDs
+
+Stack Auth includes several built-in team permissions:
+
+- **`$update_team`** - Edit team information and metadata
+- **`$delete_team`** - Delete the entire team
+- **`$invite_members`** - Send invitations to new members
+- **`$remove_members`** - Remove members from the team
+- **`$read_members`** - View team member list
+- **`team_member`** - Basic team membership (automatically granted)
+
+For more advanced team features, check out the [REST API documentation](../rest-api/overview.mdx). 
diff --git a/docs/templates-python/authentication/user-authentication.mdx b/docs/templates-python/concepts/user-authentication.mdx
similarity index 96%
rename from docs/templates-python/authentication/user-authentication.mdx
rename to docs/templates-python/concepts/user-authentication.mdx
index 04812ba52..640691258 100644
--- a/docs/templates-python/authentication/user-authentication.mdx
+++ b/docs/templates-python/concepts/user-authentication.mdx
@@ -362,14 +362,6 @@ def safe_sign_in(email, password):
     return sign_in_with_password(email, password)
 ```
 
-## Next Steps
-
-Now that you have user authentication working, you can:
-
-1. **[Manage Users](../user-management/index.mdx)** - Update user profiles, manage user data
-2. **[Handle Teams](../team-management/index.mdx)** - Implement team functionality 
-3. **[Set up OAuth](../oauth/index.mdx)** - Add social login providers
-4. **[Framework Integration](../integration/index.mdx)** - See examples for Flask, Django, and FastAPI
 
 For more advanced authentication features, check out the [REST API documentation](../rest-api/overview.mdx).
 
diff --git a/docs/templates-python/getting-started/setup.mdx b/docs/templates-python/getting-started/setup.mdx
index 2d5e44c5b..f33cab759 100644
--- a/docs/templates-python/getting-started/setup.mdx
+++ b/docs/templates-python/getting-started/setup.mdx
@@ -6,122 +6,119 @@ title: Setup
 Welcome to the Python setup guide. If you're looking for guides for other frameworks, check out the [Next.js SDK Setup](/next/getting-started/setup), [React SDK Setup](/react/getting-started/setup), or the [JavaScript SDK Setup](/js/getting-started/setup).
 </Info>
 
-Our recommended way to use Stack Auth with Python is with the [REST API](../rest-api/overview.mdx). It provides a fully documented way to interact with Stack Auth from any Python framework, including Flask, FastAPI, Django, and others.
+Our recommended way to use Stack Auth with Python is with the [REST API](../rest-api/overview.mdx). It provides a fully documented way to interact with Stack Auth from any Python framework, including Flask, FastAPI, and Django.
 
 For the purpose of this guide, we will use the `requests` library to make HTTP requests to the Stack Auth API. If you haven't already, you can install it in your environment with `pip install requests`.
 
 <Steps>
   <Step>
     ### Create API keys
+
+    First, create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), and copy your project ID, publishable client key, and secret server key into a safe place (eg. environment variables).
+
+    From there, you can access them in your Python code. You can then read them like this:
+
+    ```python
+    import os
+
+    stack_project_id = os.getenv("STACK_PROJECT_ID")
+    stack_publishable_client_key = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
+    stack_secret_server_key = os.getenv("STACK_SECRET_SERVER_KEY")
+    ```
   </Step>
 
-  First, create an account on [the Stack Auth dashboard](https://app.stack-auth.com/projects), and copy your project ID, publishable client key, and secret server key into a safe place (eg. environment variables).
-
-  From there, you can access them in your Python code. You can then read them like this:
-
-  ```python
-  import os
-
-  stack_project_id = os.getenv("STACK_PROJECT_ID")
-  stack_publishable_client_key = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
-  stack_secret_server_key = os.getenv("STACK_SECRET_SERVER_KEY")
-  ```
-
   <Step>
-    ### Create a Stack Auth client
+    ### Make a request
+
+    Next, create a helper function to make requests to the Stack Auth API:
+
+    ```python
+    import requests
+
+    def stack_auth_request(method, endpoint, **kwargs):
+      res = requests.request(
+        method,
+        f'https://api.stack-auth.com/{endpoint}',
+        headers={
+          'x-stack-access-type': 'server',  # or 'client' if you're only accessing the client API
+          'x-stack-project-id': stack_project_id,
+          'x-stack-publishable-client-key': stack_publishable_client_key,
+          'x-stack-secret-server-key': stack_secret_server_key,  # not necessary if access type is 'client'
+          **kwargs.pop('headers', {}),
+        },
+        **kwargs,
+      )
+      if res.status_code >= 400:
+        raise Exception(f"Stack Auth API request failed with {res.status_code}: {res.text}")
+      return res.json()
+
+    print(stack_auth_request('GET', '/api/v1/projects/current'))
+    ```
   </Step>
 
-  Next, create a helper class to make requests to the Stack Auth API. This will handle authentication headers and error handling:
-
-  ```python
-  import requests
-  import os
-  from typing import Optional, Dict, Any
-
-  class StackAuthClient:
-      def __init__(self):
-          self.base_url = "https://api.stack-auth.com"
-          self.project_id = os.getenv("STACK_PROJECT_ID")
-          self.publishable_client_key = os.getenv("STACK_PUBLISHABLE_CLIENT_KEY")
-          self.secret_server_key = os.getenv("STACK_SECRET_SERVER_KEY")
-          
-          if not all([self.project_id, self.publishable_client_key]):
-              raise ValueError("Missing required Stack Auth environment variables")
-      
-      def _make_request(
-          self, 
-          method: str, 
-          endpoint: str, 
-          access_type: str = "server",
-          access_token: Optional[str] = None,
-          **kwargs
-      ) -> Dict[str, Any]:
-          """Make a request to the Stack Auth API"""
-          headers = {
-              'x-stack-access-type': access_type,
-              'x-stack-project-id': self.project_id,
-              'x-stack-publishable-client-key': self.publishable_client_key,
-              'Content-Type': 'application/json',
-              **kwargs.pop('headers', {}),
-          }
-          
-          # Add server key for server access
-          if access_type == "server" and self.secret_server_key:
-              headers['x-stack-secret-server-key'] = self.secret_server_key
-          
-          # Add access token for authenticated requests
-          if access_token:
-              headers['x-stack-access-token'] = access_token
-          
-          url = f"{self.base_url}/{endpoint.lstrip('/')}"
-          
-          response = requests.request(method, url, headers=headers, **kwargs)
-          
-          if response.status_code >= 400:
-              raise Exception(f"Stack Auth API request failed with {response.status_code}: {response.text}")
-          
-          return response.json() if response.content else {}
-
-  # Initialize the client
-  stack_auth = StackAuthClient()
-  ```
-
   <Step>
-    ### Test the connection
+    ### Handle user access tokens
+
+    If you're building a backend server, most likely you'll want to use the currently signed in user's access token. Most normally, you would send this with all your requests to the backend in an HTTP header.
+
+    In Stack Auth's JavaScript SDK, you can retrieve the access token [from the `stackClientApp` object](/sdk/types/user#currentusergetauthjson). Then, you can use said access token to make requests to Stack Auth:
+
+    ```python
+    access_token = # access token retrieved from the JavaScript SDK
+
+    print(stack_auth_request('GET', '/api/v1/users/me', headers={
+      'x-stack-access-token': access_token,
+    }))
+    ```
+
+    Here's how to extract and use the access token in your Python backend:
+
+    **Extract access token from request headers:**
+
+    ```python
+    def get_access_token_from_request(request):
+        """Extract access token from x-stack-access-token header"""
+        return request.headers.get('x-stack-access-token')
+    ```
+
+    **Use the access token with Stack Auth:**
+
+    ```python
+    def get_current_user_from_token(access_token):
+        """Get current user information using their access token"""
+        return stack_auth_request('GET', '/api/v1/users/me', headers={
+            'x-stack-access-token': access_token,
+        })
+    ```
+
+    **Example usage in a Flask route:**
+    
+    ```python
+    @app.route('/api/user-profile')
+    def user_profile():
+        access_token = get_access_token_from_request(request)
+        if not access_token:
+            return {'error': 'No access token provided'}, 401
+        
+        try:
+            user_info = get_current_user_from_token(access_token)
+            return {'user': user_info}
+        except Exception as e:
+            return {'error': 'Invalid access token'}, 401
+    ```
+
   </Step>
 
-  Test that your API keys work correctly by fetching the current project:
-
-  ```python
-  # Test the connection
-  try:
-      project_info = stack_auth._make_request('GET', '/api/v1/projects/current')
-      print("✅ Successfully connected to Stack Auth!")
-      print(f"Project: {project_info.get('display_name', 'Unknown')}")
-  except Exception as e:
-      print(f"❌ Failed to connect: {e}")
-  ```
-
   <Step>
     ### Done!
   </Step>
 </Steps>
 
-## What's Next?
+## Next steps
 
 Now that you have Stack Auth set up in your Python application, you can:
 
-1. **[Implement Authentication](../authentication/index.mdx)** - Learn how to sign up and sign in users
-2. **[Manage Users](../user-management/index.mdx)** - Create, update, and retrieve user information  
-3. **[Handle Teams](../team-management/index.mdx)** - Implement team functionality
-4. **[Framework Integration](../integration/index.mdx)** - See specific examples for Flask, Django, and FastAPI
+1. **[User Authentication](../concepts/user-authentication.mdx)** - Learn how to sign up and sign in users
+2. **[Teams Management](../concepts/teams-management.mdx)** - Implement team functionality
 
-## Framework-Specific Setup
-
-While the REST API approach works with any Python framework, we also provide specific integration guides:
-
-- **[Flask Integration](../integration/flask.mdx)** - Complete Flask setup with middleware
-- **[Django Integration](../integration/django.mdx)** - Django setup with custom authentication backend
-- **[FastAPI Integration](../integration/fastapi.mdx)** - FastAPI setup with dependency injection
-
-Choose the guide that matches your framework, or continue with the general REST API approach if you're using a different framework. 
+Check out the [REST API documentation](../rest-api/overview.mdx) to learn more about the available endpoints and how to use them in your Python application.
diff --git a/docs/templates-python/integration/django.mdx b/docs/templates-python/integration/django.mdx
deleted file mode 100644
index 965a185b1..000000000
--- a/docs/templates-python/integration/django.mdx
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Django Integration
-description: Integrate Stack Auth with Django applications using middleware and decorators
----
-
-This guide is coming soon.
diff --git a/docs/templates-python/integration/meta.json b/docs/templates-python/integration/meta.json
deleted file mode 100644
index 3d40d0dee..000000000
--- a/docs/templates-python/integration/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "title": "Framework Integration",
-  "description": "Stack Auth integration patterns for Python frameworks",
-  "pages": [
-    "django",
-    "flask", 
-    "fastapi",
-    "standalone-scripts"
-  ]
-} 
diff --git a/docs/templates-python/meta.json b/docs/templates-python/meta.json
index 13afd6788..08468cb9a 100644
--- a/docs/templates-python/meta.json
+++ b/docs/templates-python/meta.json
@@ -3,21 +3,15 @@
   "description": "Stack Auth for Python applications using the REST API",
   "pages": [
     "overview",
+    "faq",
     "---Getting Started---",
     "getting-started/setup",
-    "getting-started/auth-providers",
-    "---Authentication Flows---",
-    "authentication",
-    "---User Management---", 
-    "user-management",
-    "---Team & Organization Management---",
-    "team-management", 
-    "---Framework Integration---",
-    "integration",
-    "---Backend Concepts---",
-    "concepts/backend-integration",
-    "---Other Resources---",
-    "others",
-    "faq"
+    "---Concepts---",
+    "concepts/user-authentication",
+    "concepts/teams-management",
+    "---Integration---",
+    "---Other---",
+    "others/self-host",
+    "others/cli-authentication"
   ]
 } 
diff --git a/docs/templates-python/team-management/meta.json b/docs/templates-python/team-management/meta.json
deleted file mode 100644
index aa083602c..000000000
--- a/docs/templates-python/team-management/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "title": "Team Management",
-  "description": "Team and organization operations via the REST API", 
-  "pages": [
-    "team-operations",
-    "team-invitations",
-    "team-permissions",
-    "organization-management"
-  ]
-} 
diff --git a/docs/templates-python/user-management/meta.json b/docs/templates-python/user-management/meta.json
deleted file mode 100644
index bdef5e5a9..000000000
--- a/docs/templates-python/user-management/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "title": "User Management", 
-  "description": "User operations and data management via the REST API",
-  "pages": [
-    "create-users",
-    "user-operations",
-    "custom-user-data",
-    "user-permissions"
-  ]
-}