Add Organizations documentation for OpenHands Cloud

docs.json

@@ -411,6 +411,16 @@
               }
             ]
           },
+          {
+            "group": "Organizations",
+            "icon": "building",
+            "pages": [
+              "openhands/usage/cloud/organizations/overview",
+              "openhands/usage/cloud/organizations/managing-members",
+              "openhands/usage/cloud/organizations/roles-permissions",
+              "openhands/usage/cloud/organizations/settings"
+            ]
+          },
           {
             "group": "Automations (BETA)",
             "icon": "clock",

openhands/usage/cloud/organizations/managing-members.mdx

@@ -0,0 +1,54 @@
+---
+title: Managing Members
+description: How to invite users and manage team members in your organization.
+---
+
+## Inviting Users
+
+To add a new member to your organization:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Click **Invite Organization Members** in the menu.
+3. Enter the email address of the user you want to invite.
+4. Click **Add**.
+
+The invited user will receive an email with instructions to accept the invitation and join your organization.
+Once they accept, they will be added as a **Member** by default.
+
+<Note>
+  Invitations expire after 7 days. If the invitation expires, you'll need to send a new one.
+</Note>
+
+## Changing User Roles
+
+After a user has joined your organization, an Admin or Owner can modify their role:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Org Members**.
+3. Find the user whose role you want to change.
+4. Click the role dropdown next to their name.
+5. Select the new role: `Owner`, `Admin`, or `Member`.
+6. Confirm the change.
+
+<Warning>
+  Changing a user's role takes effect immediately. Be careful when demoting users, as they will lose access
+  to features associated with their previous role.
+</Warning>
+
+## Removing Members
+
+To remove a member from your organization:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Org Members**.
+3. Find the user you want to remove.
+4. Click the **Remove** button next to their name.
+5. Confirm the removal.
+
+Removed members will lose access to the organization's shared resources immediately, but their private
+conversations will remain intact.
+
+## Next Steps
+
+- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand what each role can do.
+- [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure your organization's resources.

openhands/usage/cloud/organizations/overview.mdx

@@ -0,0 +1,43 @@
+---
+title: Organizations Overview
+description: Manage teams and collaborate with shared resources in OpenHands Cloud or OpenHands Enterprise.
+---
+
+## What are Organizations?
+
+Organizations allow multiple users to collaborate within a shared workspace in OpenHands Cloud or OpenHands Enterprise. With
+Organizations, teams can share a pool of credits, use consistent LLM configurations, and streamline access
+to repositories.
+
+<Note>
+  Organizations is a commercial feature available with an OpenHands Cloud subscription or OpenHands Enterprise.
+</Note>
+
+## Key Features
+
+Organizations provide the following capabilities:
+
+- **Multiple Users** - Add team members to a common organization for centralized management.
+- **Shared Credits** - Pool OpenHands Cloud credits across all organization members.
+- **Default LLM Configuration** - Define the default model provider and LLM that all members can use.
+- **Git Organization Claiming** - Claim specific Git organizations to route OpenHands resolver requests to your organization.
+
+## Conversation Visibility
+
+By default, conversations remain **private to individual members** of an organization. Each user's conversations
+are only visible to them. 
+
+## Getting Started
+
+To start using Organizations:
+
+1. Subscribe to an OpenHands Cloud plan or OpenHands Enterprise.
+2. Create a new organization from the OpenHands Cloud dashboard.
+3. [Invite team members](/openhands/usage/cloud/organizations/managing-members) to join your organization.
+4. Configure your organization's [LLM settings](/openhands/usage/cloud/organizations/settings) and shared resources.
+
+## Next Steps
+
+- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Learn how to invite users and manage roles.
+- [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure LLM providers, credits, and Git organization claims.
+- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand the different permission levels.

openhands/usage/cloud/organizations/roles-permissions.mdx

@@ -0,0 +1,82 @@
+---
+title: Roles and Permissions
+description: Understanding the different permission levels in OpenHands Organizations.
+---
+
+## Overview
+
+Organizations in OpenHands support three roles, each with different levels of access and capabilities:
+**Member**, **Admin**, and **Owner**. This page describes what each role can do.
+
+## Permissions Table
+
+| Permission | Member | Admin | Owner |
+|------------|:------:|:-----:|:-----:|
+| Create conversations | ✓ | ✓ | ✓ |
+| Manage private settings | ✓ | ✓ | ✓ |
+| Invite users | | ✓ | ✓ |
+| Elevate users to Admin role | | ✓ | ✓ |
+| Add credits | | ✓ | ✓ |
+| Modify LLM settings | | ✓ | ✓ |
+| Elevate users to Owner role | | | ✓ |
+| Claim Git organizations | | | ✓ |
+| Delete organization | | | ✓ |
+
+## Role Descriptions
+
+### Member
+
+Members are the default role for users joining an organization. Members can:
+
+- **Create conversations** - Start new conversations using the organization's shared credits.
+- **Manage their own private settings** - Configure settings that are only visible to them, including:
+  - MCP servers
+  - Secrets
+  - API keys
+  - Git user settings
+  - Slack integration
+
+Members cannot invite new users, modify organization-wide settings (like LLM settings), or manage other users' roles.
+
+### Admin
+
+Admins have all the capabilities of Members, plus the ability to manage the organization's settings and users. Admins can:
+
+- Everything a Member can do.
+- **Invite users** - Send invitations to new team members.
+- **Change user roles** - Promote Members to Admin or demote Admins to Members.
+- **Add credits** - Purchase and add credits to the organization's shared pool.
+- **Modify LLM settings** - Configure the default LLM provider and model for the organization.
+
+Admins cannot delete the organization or claim Git organizations.
+
+### Owner
+
+Owners have full control over the organization. Owners can:
+
+- Everything an Admin can do.
+- **Delete the organization** - Permanently remove the organization and all associated data.
+- **Claim Git organizations** - Link specific Git organizations to route OpenHands resolver requests to this organization.
+
+<Note>
+  Every organization must have at least one Owner. If you need to transfer ownership, first promote another
+  user to Owner before changing your own role.
+</Note>
+
+## Private Settings
+
+Regardless of role, all organization members have control over their own **private settings**. These settings
+are personal to each user and are not visible to other organization members, including Admins and Owners.
+
+Private settings include:
+
+- **MCP Servers** - Configure Model Context Protocol servers.
+- **Secrets** - Store sensitive values like API tokens and credentials.
+- **API Keys** - Manage keys for programmatic access to OpenHands.
+- **Git Settings** - Configure personal Git authentication and preferences.
+- **Slack Integration** - Connect your personal Slack workspace.
+
+## Next Steps
+
+- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Learn how to invite and manage users.
+- [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure organization-wide settings.

openhands/usage/cloud/organizations/settings.mdx

@@ -0,0 +1,90 @@
+---
+title: Organization Settings
+description: Configure shared resources and settings for your OpenHands organization.
+---
+
+## Overview
+
+Organization settings allow Admins and Owners to configure shared resources that all members can use. This
+includes LLM configurations, credits management, and Git organization claims.
+
+## LLM Configuration
+
+<Note>
+  Modifying LLM settings requires Admin or Owner permissions.
+</Note>
+
+Organizations can define a default LLM provider and model that all members will use:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. Select the `LLM` tab.
+2. Select the `LLM` tab.
+3. Choose your preferred **LLM provider** from the available options.
+4. Select the **model** you want to use as the default.
+5. Click `Save Changes`.
+
+All organization members will use this LLM configuration for their conversations unless they have configured
+personal overrides.
+
+## Managing Credits
+
+<Note>
+  Adding credits requires Admin or Owner permissions.
+</Note>
+
+Organization credits are shared across all members. To add credits:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. Click **+ Add**.
+4. Choose the amount of credits to purchase.
+5. Complete the payment process.
+
+Credits will be added to the organization's shared pool immediately and can be used by any member.
+
+### Monitoring Usage
+
+You can monitor credit usage from the **Organization** settings page, which shows the current credit balance.
+
+For detailed usage reporting at the user level, use the API endpoint:
+
+```
+GET /api/organizations/{org_id}/members/financial
+```
+
+This endpoint provides financial usage data for all members within your organization.
+
+## Claiming Git Organizations
+
+<Note>
+  Claiming Git organizations requires Owner permissions.
+</Note>
+
+Claiming a Git organization links it to your OpenHands organization, allowing OpenHands resolver requests
+for repositories in that Git organization to be routed to your organization.
+
+Owners have the ability to claim a Git organization:
+
+1. Hover over the profile icon in the lower left — an account menu will appear.
+2. Select **Organization**.
+3. In the **Git Conversation Routing** section, Git organizations from your linked GitHub/GitLab accounts are listed automatically.
+4. Click **Claim** next to the Git organization you want to link to your OpenHands organization.
+
+<Warning>
+  You must have admin access to the Git organization to claim it. The verification process confirms your
+  authorization.
+</Warning>
+
+### Benefits of Claiming Git Organizations
+
+When a Git organization is claimed:
+
+- All resolver requests for repositories in that Git organization are automatically routed to your OpenHands organization.
+- Organization members can work seamlessly with repositories in the claimed Git organization.
+- Usage is tracked against your organization's credit pool.
+
+## Next Steps
+
+- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles.
+- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand permission levels.