update_organization
Modify organization settings in Terraform Cloud, including email, authentication policies, session timeouts, execution modes, and workspace management options. Update specific attributes without altering others.
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_tools.md for usage examples
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | ||
| params | No |
Input Schema (JSON Schema)
{
"$defs": {
"CollaboratorAuthPolicy": {
"description": "Authentication policy options for organization collaborators.\n\nDefines the authentication requirements for organization members:\n- PASSWORD: Password-only authentication is allowed\n- TWO_FACTOR_MANDATORY: Two-factor authentication is required for all users\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations#authentication\n\nSee:\n docs/models/organization_examples.md for usage examples",
"enum": [
"password",
"two_factor_mandatory"
],
"title": "CollaboratorAuthPolicy",
"type": "string"
},
"ExecutionMode": {
"description": "Execution mode options for workspaces and organizations.\n\nDefines how Terraform operations are executed:\n- REMOTE: Terraform runs on Terraform Cloud's infrastructure\n- LOCAL: Terraform runs on your local machine\n- AGENT: Terraform runs on your own infrastructure using an agent\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode\n\nSee:\n docs/models/workspace_examples.md for usage examples",
"enum": [
"remote",
"local",
"agent"
],
"title": "ExecutionMode",
"type": "string"
},
"OrganizationParams": {
"description": "Parameters for organization operations without routing fields.\n\nThis model provides all optional parameters that can be used when creating or updating\norganizations, reusing the field definitions from BaseOrganizationRequest.\n\nReference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations\n\nNote:\n All fields are inherited from BaseOrganizationRequest.\n\nSee:\n docs/models/organization_examples.md for usage examples",
"properties": {
"aggregated-commit-status-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether to aggregate VCS status updates",
"title": "Aggregated-Commit-Status-Enabled"
},
"allow-force-delete-workspaces": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether workspace admins can delete workspaces with resources",
"title": "Allow-Force-Delete-Workspaces"
},
"assessments-enforced": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to compel health assessments for all eligible workspaces",
"title": "Assessments-Enforced"
},
"collaborator-auth-policy": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/CollaboratorAuthPolicy"
},
{
"type": "null"
}
],
"default": "password",
"description": "Authentication policy",
"title": "Collaborator-Auth-Policy"
},
"cost-estimation-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether cost estimation is enabled for all workspaces",
"title": "Cost-Estimation-Enabled"
},
"default-agent-pool-id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The ID of the agent pool (required when default_execution_mode is 'agent')",
"title": "Default-Agent-Pool-Id"
},
"default-execution-mode": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/ExecutionMode"
},
{
"type": "null"
}
],
"default": "remote",
"description": "Default execution mode",
"title": "Default-Execution-Mode"
},
"email": {
"anyOf": [
{
"pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Admin email address",
"title": "Email"
},
"name": {
"anyOf": [
{
"minLength": 3,
"pattern": "^[a-z0-9][-a-z0-9_]*[a-z0-9]$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name of the organization",
"title": "Name"
},
"owners-team-saml-role-id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "SAML only - the name of the 'owners' team",
"title": "Owners-Team-Saml-Role-Id"
},
"send-passing-statuses-for-untriggered-speculative-plans": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"description": "Whether to send VCS status updates for untriggered plans",
"title": "Send-Passing-Statuses-For-Untriggered-Speculative-Plans"
},
"session-remember": {
"anyOf": [
{
"maximum": 43200,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 20160,
"description": "Session expiration in minutes",
"title": "Session-Remember"
},
"session-timeout": {
"anyOf": [
{
"maximum": 43200,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 20160,
"description": "Session timeout after inactivity in minutes",
"title": "Session-Timeout"
},
"speculative-plan-management-enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"description": "Whether to enable automatic cancellation of plan-only runs",
"title": "Speculative-Plan-Management-Enabled"
}
},
"title": "OrganizationParams",
"type": "object"
}
},
"properties": {
"organization": {
"title": "Organization",
"type": "string"
},
"params": {
"anyOf": [
{
"$ref": "#/$defs/OrganizationParams"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"organization"
],
"title": "update_organizationArguments",
"type": "object"
}