Skip to main content

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

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.
  • View organization conversations and usage - See every conversation in the organization and its usage. See Conversation Usage Access.
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.
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.

Conversation Usage Access

Available in OpenHands Enterprise 0.110.0 and later.

Default Access

Owners and Admins can view every conversation in the organization, including conversations created by other users, from the Dashboard page in Settings or with List Org Conversations. The dashboard shows each conversation’s creator, total cost, and token usage, together with aggregate usage across conversations. The API also returns each conversation’s title, tags, and status. This access doesn’t depend on the detailed usage setting. Members can view their own conversations, but can’t view the organization’s conversation list or usage reports.

Detailed Usage

Use detailed usage to see how the cost and tokens inside a conversation are split across the main agent, sub-agent tasks and condenser, together with recorded models and task timing. This helps identify which parts of a run account for its usage. For an Owner or Admin viewing organization conversations: Detailed usage is off by default for both new and existing organizations. When enabled, it is available to the organization’s Owners and Admins. Members and service accounts don’t get this access. Get Org Conversation Usage (GET /api/organizations/{org_id}/conversations/{conversation_id}/usage) is read-only and returns usage data without prompts, messages, task descriptions, or tool inputs and outputs. Missing history can leave the breakdown incomplete. Check completeness (full, partial, or totals_only) and incomplete_reasons in the response.

Enable or Disable Detailed Usage

There is no UI or Helm setting. As an Owner or Admin, set enable_conversation_usage_detail to true with Update Org (PATCH /api/organizations/{org_id}). Set OH_BASE_URL, ORG_ID, and OH_API_KEY for your deployment, then send:
Set it to false to turn detailed usage off. The change takes effect immediately, and Get Org Conversation Usage returns 403 until you turn it on again. Conversation lists and total-usage reports aren’t affected. The setting applies per organization. Check the current value with Get Org.

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