Implementation:OpenHands OpenHands OrgService Create LiteLLM Integration

Knowledge Sources	OpenHands
Domains	Organization_Management, Multi_Tenancy
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for provisioning LiteLLM team and API key resources during organization onboarding provided by the OpenHands enterprise storage layer.

Description

OrgService.create_litellm_integration provisions the external LiteLLM resources required for a new organization. It performs two sequential operations through the LiteLLM proxy API:

1. Team creation via LiteLlmManager._create_team(client, team_alias, team_id, max_budget) — establishes a LiteLLM team that serves as the organization's usage boundary, associating the organization ID as the team alias and applying a default maximum budget.
2. API key generation via LiteLlmManager._generate_key(client, keycloak_user_id, team_id, key_alias, metadata) -> str | None — creates a LiteLLM API key bound to the creating user and the newly created team, enabling the user to make LLM requests on behalf of the organization.

The method returns a dictionary containing the provisioned settings (team ID, API key hash, budget information) which are later applied to the organization entity via apply_litellm_settings_to_org.

Usage

Call this method after name validation succeeds but before creating the organization entity in the database. The returned settings dictionary is consumed by the entity construction step to populate LiteLLM-related fields on the Org model.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/storage/org_service.py
• Lines: L48-87

Signature

async def create_litellm_integration(
    self,
    org_id: UUID,
    user_id: str,
) -> dict:
    """Provision a LiteLLM team and API key for the new organization.

    Args:
        org_id: The UUID of the organization being created.
        user_id: The Keycloak user ID of the organization creator.

    Returns:
        A dictionary containing the provisioned LiteLLM settings
        (team_id, api_key, max_budget, etc.).
    """

Import

from enterprise.storage.org_service import OrgService

I/O Contract

Inputs

Name	Type	Required	Description
org_id	UUID	Yes	The UUID assigned to the organization being created
user_id	str	Yes	The Keycloak user ID of the user creating the organization

Outputs

Name	Type	Description
settings	dict	Dictionary containing provisioned LiteLLM settings including team_id, api_key_hash, and max_budget values

Usage Examples

Basic Usage

from uuid import uuid4
from enterprise.storage.org_service import OrgService

org_service = OrgService(session=db_session)
org_id = uuid4()
user_id = "keycloak-user-abc123"

# Provision LiteLLM resources before creating the org entity
litellm_settings = await org_service.create_litellm_integration(
    org_id=org_id,
    user_id=user_id,
)

# litellm_settings now contains team_id, api_key, budget info
# Pass these settings to create_org_entity or apply_litellm_settings_to_org

Related Pages

Implements Principle

• Principle:OpenHands_OpenHands_LiteLLM_Provisioning

Environment

• Environment:OpenHands_OpenHands_SaaS_Server_Environment