update_organization
Modify Terraform Cloud organization settings including email, authentication policies, session timeouts, cost estimation, and workspace execution modes.
Instructions
Update an existing organization in Terraform Cloud
Modifies organization settings such as email contact, authentication policy, or other configuration options. Only specified attributes will be updated.
API endpoint: PATCH /organizations/{organization}
Args: organization: The name of the organization to update (required) params: Organization parameters to update: - email: Admin email address for the organization - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources
Returns: The updated organization with all current settings
See: docs/tools/organization.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | ||
| params | No |
Implementation Reference
- The primary handler function implementing the update_organization tool logic. It constructs an OrganizationUpdateRequest from input parameters, creates the API payload, and performs a PATCH request to the Terraform Cloud /organizations/{organization} endpoint.
@handle_api_errors async def update_organization( organization: str, params: Optional[OrganizationParams] = None ) -> APIResponse: """Update an existing organization in Terraform Cloud Modifies organization settings such as email contact, authentication policy, or other configuration options. Only specified attributes will be updated. API endpoint: PATCH /organizations/{organization} Args: organization: The name of the organization to update (required) params: Organization parameters to update: - email: Admin email address for the organization - collaborator_auth_policy: Authentication policy (password or two_factor_mandatory) - session_timeout: Session timeout after inactivity in minutes - session_remember: Session total expiration time in minutes - cost_estimation_enabled: Whether to enable cost estimation for workspaces - default_execution_mode: Default workspace execution mode (remote, local, agent) - aggregated_commit_status_enabled: Whether to aggregate VCS status updates - speculative_plan_management_enabled: Whether to auto-cancel unused speculative plans - assessments_enforced: Whether to enforce health assessments for all workspaces - allow_force_delete_workspaces: Whether to allow deleting workspaces with resources Returns: The updated organization with all current settings See: docs/tools/organization.md for reference documentation """ # Extract parameters from the params object if provided param_dict = params.model_dump(exclude_none=True) if params else {} # Create request using Pydantic model request = OrganizationUpdateRequest(organization=organization, **param_dict) # Create API payload using utility function payload = create_api_payload( resource_type="organizations", model=request, exclude_fields={"organization"} ) # Make the API request return await api_request( f"organizations/{organization}", method="PATCH", data=payload ) - Pydantic model OrganizationUpdateRequest used for input validation and payload construction in the update_organization handler. Inherits fields from BaseOrganizationRequest and adds the required organization identifier.
class OrganizationUpdateRequest(BaseOrganizationRequest): """Request model for updating a Terraform Cloud organization. Validates and structures the request according to the Terraform Cloud API requirements for updating organizations. All fields are optional. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations#update-an-organization Note: This inherits all configuration fields from BaseOrganizationRequest and adds a required organization field for routing. See: docs/models/organization.md for reference """ # Add organization field which is required for updates but not part of the attributes organization: str = Field( ..., # No alias needed as field name matches API field name description="The name of the organization to update", ) - Base Pydantic model defining all configurable fields for organization updates, used by OrganizationUpdateRequest and OrganizationParams. Includes validation rules, defaults, and descriptions matching the Terraform Cloud API.
class BaseOrganizationRequest(APIRequest): """Base class for organization create and update requests with common fields. This includes all fields that are commonly used in request payloads for the organization creation and update APIs. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations Note: This class inherits model_config from APIRequest -> BaseModelConfig See: docs/models/organization.md for fields and usage examples """ # Fields common to both create and update requests with API defaults from docs name: Optional[str] = Field( None, # No alias needed as field name matches API field name description="Name of the organization", min_length=3, pattern=r"^[a-z0-9][-a-z0-9_]*[a-z0-9]$", ) email: Optional[str] = Field( None, # No alias needed as field name matches API field name description="Admin email address", pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$", ) session_timeout: Optional[int] = Field( 20160, alias="session-timeout", description="Session timeout after inactivity in minutes", ge=1, le=43200, # 30 days in minutes ) session_remember: Optional[int] = Field( 20160, alias="session-remember", description="Session expiration in minutes", ge=1, le=43200, # 30 days in minutes ) collaborator_auth_policy: Optional[Union[str, CollaboratorAuthPolicy]] = Field( CollaboratorAuthPolicy.PASSWORD, alias="collaborator-auth-policy", description="Authentication policy", ) cost_estimation_enabled: Optional[bool] = Field( False, alias="cost-estimation-enabled", description="Whether cost estimation is enabled for all workspaces", ) send_passing_statuses_for_untriggered_speculative_plans: Optional[bool] = Field( False, alias="send-passing-statuses-for-untriggered-speculative-plans", description="Whether to send VCS status updates for untriggered plans", ) aggregated_commit_status_enabled: Optional[bool] = Field( True, alias="aggregated-commit-status-enabled", description="Whether to aggregate VCS status updates", ) speculative_plan_management_enabled: Optional[bool] = Field( True, alias="speculative-plan-management-enabled", description="Whether to enable automatic cancellation of plan-only runs", ) owners_team_saml_role_id: Optional[str] = Field( None, alias="owners-team-saml-role-id", description="SAML only - the name of the 'owners' team", ) assessments_enforced: Optional[bool] = Field( False, alias="assessments-enforced", description="Whether to compel health assessments for all eligible workspaces", ) allow_force_delete_workspaces: Optional[bool] = Field( False, alias="allow-force-delete-workspaces", description="Whether workspace admins can delete workspaces with resources", ) default_execution_mode: Optional[Union[str, ExecutionMode]] = Field( ExecutionMode.REMOTE, alias="default-execution-mode", description="Default execution mode", ) default_agent_pool_id: Optional[str] = Field( None, alias="default-agent-pool-id", description="The ID of the agent pool (required when default_execution_mode is 'agent')", ) - Pydantic model OrganizationParams directly used as optional parameter type in the update_organization handler function signature, inheriting all updateable fields from BaseOrganizationRequest.
class OrganizationParams(BaseOrganizationRequest): """Parameters for organization operations without routing fields. This model provides all optional parameters that can be used when creating or updating organizations, reusing the field definitions from BaseOrganizationRequest. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations Note: All fields are inherited from BaseOrganizationRequest. See: docs/models/organization.md for reference """ # Inherits model_config and all fields from BaseOrganizationRequest - terraform_cloud_mcp/server.py:79-79 (registration)Registration of the update_organization tool in the FastMCP server using mcp.tool decorator with write_tool_config, enabling it conditionally based on environment settings.
mcp.tool(**write_tool_config)(organizations.update_organization)