create_organization
Create a new Terraform Cloud organization with specified name and email, enabling workspace and team management. Configure authentication, execution modes, and workspace policies for secure and scalable infrastructure setup.
Instructions
Create a new organization in Terraform Cloud
Creates a new organization with the given name and email, allowing workspaces
and teams to be created within it. This is the first step in setting up a new
environment in Terraform Cloud.
API endpoint: POST /organizations
Args:
name: The name of the organization (required)
email: Admin email address (required)
params: Additional organization settings:
- 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
- default_agent_pool_id: Default agent pool ID (required when using agent mode)
Returns:
The created organization details including ID and created timestamp
See:
docs/tools/organization_tools.md for usage examples
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| name | 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": {
"email": {
"title": "Email",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"params": {
"anyOf": [
{
"$ref": "#/$defs/OrganizationParams"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"name",
"email"
],
"title": "create_organizationArguments",
"type": "object"
}