A new platform for documentation and tutorials is launching soon.

We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.

»Organizations API

The Organizations API is used to list, show, create, update, and destroy organizations.

»List Organizations

GET /organizations

Status	Response	Reason
200	JSON API document (`type: "organizations"`)	The request was successful
404	JSON API error object	Organization not found or user unauthorized to perform action

»Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Currently, this endpoint returns a full, unpaginated list of organizations (without pagination metadata) if both of the pagination query parameters are omitted. To avoid inconsistent behavior, we recommend always supplying pagination parameters when building against this API.

Parameter	Description
`q`	Optional. A search query string. Organizations are searchable by name and notification email. This query takes precedence over the attribute specific searches `q[email]` or `q[name]`.
`q[email]`	Optional. A search query string. This query searches organizations by notification email. If used with `q[name]`, it returns organizations that match both queries.
`q[name]`	Optional. A search query string. This query searches organizations by name. If used with `q[email]`, it returns organizations that match both queries.
`page[number]`	Optional. Defaults to the first page, if omitted when `page[size]` is provided.
`page[size]`	Optional. Defaults to 20 organizations per page, if omitted when `page[number]` is provided.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations\?page\[number\]\=1\&page\[size\]\=20

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations\?page\[number\]\=1\&page\[size\]\=20

»Sample Response

Note: Only Terraform Cloud organizations return the two-factor-conformant and assessments-enforced properties. Health assessments are not available in Terraform Enterprise.

{
  "data": [
    {
      "id": "hashicorp",
      "type": "organizations",
      "attributes": {
        "external-id": "org-Hysjx5eUviuKVCJY",
        "created-at": "2021-08-24T23:10:04.675Z",
        "email": "hashicorp@example.com",
        "session-timeout": null,
        "session-remember": null,
        "collaborator-auth-policy": "password",
        "plan-expired": false,
        "plan-expires-at": null,
        "plan-is-trial": false,
        "plan-is-enterprise": false,
        "plan-identifier": "developer",
        "cost-estimation-enabled": true,
        "send-passing-statuses-for-untriggered-speculative-plans": true,
        "name": "hashicorp",
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-access-via-teams": true,
          "can-create-module": true,
          "can-create-team": true,
          "can-create-workspace": true,
          "can-manage-users": true,
          "can-manage-subscription": true,
          "can-manage-sso": true,
          "can-update-oauth": true,
          "can-update-sentinel": true,
          "can-update-ssh-keys": true,
          "can-update-api-token": true,
          "can-traverse": true,
          "can-start-trial": true,
          "can-update-agent-pools": true,
          "can-manage-tags": true,
          "can-manage-varsets": true,
          "can-read-varsets": true,
          "can-manage-public-providers": true,
          "can-create-provider": true,
          "can-manage-public-modules": true,
          "can-manage-custom-providers": false,
          "can-manage-run-tasks": false,
          "can-read-run-tasks": false
        },
        "fair-run-queuing-enabled": true,
        "saml-enabled": false,
        "owners-team-saml-role-id": null,
        "two-factor-conformant": false,
        "assessments-enforced": false
      },
      "relationships": {
        "oauth-tokens": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/oauth-tokens"
          }
        },
        "authentication-token": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/authentication-token"
          }
        },
        "entitlement-set": {
          "data": {
            "id": "org-Hysjx5eUviuKVCJY",
            "type": "entitlement-sets"
          },
          "links": {
            "related": "/api/v2/organizations/hashicorp/entitlement-set"
          }
        },
        "subscription": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/subscription"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/hashicorp"
      }
    },
    {
      "id": "hashicorp-two",
      "type": "organizations",
      "attributes": {
        "external-id": "org-iJ5tr4WgB4WpA1hD",
        "created-at": "2022-01-04T18:57:16.036Z",
        "email": "hashicorp@example.com",
        "session-timeout": null,
        "session-remember": null,
        "collaborator-auth-policy": "password",
        "plan-expired": false,
        "plan-expires-at": null,
        "plan-is-trial": false,
        "plan-is-enterprise": false,
        "plan-identifier": "free",
        "cost-estimation-enabled": false,
        "send-passing-statuses-for-untriggered-speculative-plans": false,
        "name": "hashicorp-two",
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-access-via-teams": true,
          "can-create-module": true,
          "can-create-team": false,
          "can-create-workspace": true,
          "can-manage-users": true,
          "can-manage-subscription": true,
          "can-manage-sso": false,
          "can-update-oauth": true,
          "can-update-sentinel": false,
          "can-update-ssh-keys": true,
          "can-update-api-token": true,
          "can-traverse": true,
          "can-start-trial": true,
          "can-update-agent-pools": false,
          "can-manage-tags": true,
          "can-manage-varsets": true,
          "can-read-varsets": true,
          "can-manage-public-providers": true,
          "can-create-provider": true,
          "can-manage-public-modules": true,
          "can-manage-custom-providers": false,
          "can-manage-run-tasks": false,
          "can-read-run-tasks": false
        },
        "fair-run-queuing-enabled": true,
        "saml-enabled": false,
        "owners-team-saml-role-id": null,
        "two-factor-conformant": false,
        "assessments-enforced": false
      },
      "relationships": {
        "oauth-tokens": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/oauth-tokens"
          }
        },
        "authentication-token": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/authentication-token"
          }
        },
        "entitlement-set": {
          "data": {
            "id": "org-iJ5tr4WgB4WpA1hD",
            "type": "entitlement-sets"
          },
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/entitlement-set"
          }
        },
        "subscription": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/subscription"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/hashicorp-two"
      }
    }
  ],
  "links": {
    "self": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 2
    }
  }
}

{
  "data": [
    {
      "id": "hashicorp",
      "type": "organizations",
      "attributes": {
        "external-id": "org-Hysjx5eUviuKVCJY",
        "created-at": "2021-08-24T23:10:04.675Z",
        "email": "hashicorp@example.com",
        "session-timeout": null,
        "session-remember": null,
        "collaborator-auth-policy": "password",
        "plan-expired": false,
        "plan-expires-at": null,
        "plan-is-trial": false,
        "plan-is-enterprise": false,
        "plan-identifier": "developer",
        "cost-estimation-enabled": true,
        "send-passing-statuses-for-untriggered-speculative-plans": true,
        "name": "hashicorp",
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-access-via-teams": true,
          "can-create-module": true,
          "can-create-team": true,
          "can-create-workspace": true,
          "can-manage-users": true,
          "can-manage-subscription": true,
          "can-manage-sso": true,
          "can-update-oauth": true,
          "can-update-sentinel": true,
          "can-update-ssh-keys": true,
          "can-update-api-token": true,
          "can-traverse": true,
          "can-start-trial": true,
          "can-update-agent-pools": true,
          "can-manage-tags": true,
          "can-manage-varsets": true,
          "can-read-varsets": true,
          "can-manage-public-providers": true,
          "can-create-provider": true,
          "can-manage-public-modules": true,
          "can-manage-custom-providers": false,
          "can-manage-run-tasks": false,
          "can-read-run-tasks": false
        },
        "fair-run-queuing-enabled": true,
        "saml-enabled": false,
        "owners-team-saml-role-id": null,
        "two-factor-conformant": false,
        "assessments-enforced": false
      },
      "relationships": {
        "oauth-tokens": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/oauth-tokens"
          }
        },
        "authentication-token": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/authentication-token"
          }
        },
        "entitlement-set": {
          "data": {
            "id": "org-Hysjx5eUviuKVCJY",
            "type": "entitlement-sets"
          },
          "links": {
            "related": "/api/v2/organizations/hashicorp/entitlement-set"
          }
        },
        "subscription": {
          "links": {
            "related": "/api/v2/organizations/hashicorp/subscription"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/hashicorp"
      }
    },
    {
      "id": "hashicorp-two",
      "type": "organizations",
      "attributes": {
        "external-id": "org-iJ5tr4WgB4WpA1hD",
        "created-at": "2022-01-04T18:57:16.036Z",
        "email": "hashicorp@example.com",
        "session-timeout": null,
        "session-remember": null,
        "collaborator-auth-policy": "password",
        "plan-expired": false,
        "plan-expires-at": null,
        "plan-is-trial": false,
        "plan-is-enterprise": false,
        "plan-identifier": "free",
        "cost-estimation-enabled": false,
        "send-passing-statuses-for-untriggered-speculative-plans": false,
        "name": "hashicorp-two",
        "permissions": {
          "can-update": true,
          "can-destroy": true,
          "can-access-via-teams": true,
          "can-create-module": true,
          "can-create-team": false,
          "can-create-workspace": true,
          "can-manage-users": true,
          "can-manage-subscription": true,
          "can-manage-sso": false,
          "can-update-oauth": true,
          "can-update-sentinel": false,
          "can-update-ssh-keys": true,
          "can-update-api-token": true,
          "can-traverse": true,
          "can-start-trial": true,
          "can-update-agent-pools": false,
          "can-manage-tags": true,
          "can-manage-varsets": true,
          "can-read-varsets": true,
          "can-manage-public-providers": true,
          "can-create-provider": true,
          "can-manage-public-modules": true,
          "can-manage-custom-providers": false,
          "can-manage-run-tasks": false,
          "can-read-run-tasks": false
        },
        "fair-run-queuing-enabled": true,
        "saml-enabled": false,
        "owners-team-saml-role-id": null,
        "two-factor-conformant": false,
        "assessments-enforced": false
      },
      "relationships": {
        "oauth-tokens": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/oauth-tokens"
          }
        },
        "authentication-token": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/authentication-token"
          }
        },
        "entitlement-set": {
          "data": {
            "id": "org-iJ5tr4WgB4WpA1hD",
            "type": "entitlement-sets"
          },
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/entitlement-set"
          }
        },
        "subscription": {
          "links": {
            "related": "/api/v2/organizations/hashicorp-two/subscription"
          }
        }
      },
      "links": {
        "self": "/api/v2/organizations/hashicorp-two"
      }
    }
  ],
  "links": {
    "self": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 2
    }
  }
}

»Show an Organization

GET /organizations/:organization_name

Parameter	Description
`:organization_name`	The name of the organization to show

Status	Response	Reason
200	JSON API document (`type: "organizations"`)	The request was successful
404	JSON API error object	Organization not found or user unauthorized to perform action

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/hashicorp

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/hashicorp

»Sample Response

Note: Only Terraform Cloud organizations return the two-factor-conformant and assessments-enforced properties. Health assessments are not available in Terraform Enterprise.

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-WV6DfwfxxXvLfvfs",
      "created-at": "2020-03-26T22:13:38.456Z",
      "email": "user@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-WV6DfwfxxXvLfvfs",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  }
}

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-WV6DfwfxxXvLfvfs",
      "created-at": "2020-03-26T22:13:38.456Z",
      "email": "user@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-WV6DfwfxxXvLfvfs",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  }
}

»Create an Organization

POST /organizations

Status	Response	Reason
201	JSON API document (`type: "organizations"`)	The organization was successfully created
404	JSON API error object	Organization not found or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

»Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"organizations"`
`data.attributes.name`	string		Name of the organization
`data.attributes.email`	string		Admin email address
`data.attributes.session-timeout`	integer	20160	Session timeout after inactivity (minutes)
`data.attributes.session-remember`	integer	20160	Session expiration (minutes)
`data.attributes.collaborator-auth-policy`	string	password	Authentication policy (`password` or `two_factor_mandatory`)
`data.attributes.cost-estimation-enabled`	boolean	true	Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to true. In a Terraform Cloud organization that does not have Teams & Governance features, this value is always false and cannot be changed. In Terraform Enterprise, Cost Estimation must also be enabled in Site Administration.
`data.attributes.send-passing-statuses-for-untriggered-speculative-plans`	boolean	false	Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration.
`data.attributes.owners-team-saml-role-id`	string	(nothing)	Optional. SAML only The name of the "owners" team
`data.attributes.assessments-enforced`	boolean	(false)	Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. Not available in Terraform Enterprise.

»Sample Payload

{
  "data": {
    "type": "organizations",
    "attributes": {
      "name": "hashicorp",
      "email": "user@example.com"
    }
  }
}

{
  "data": {
    "type": "organizations",
    "attributes": {
      "name": "hashicorp",
      "email": "user@example.com"
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations

»Sample Response

Note: Only Terraform Cloud organizations return the two-factor-conformant and assessments-enforced properties. Health assessments are not available in Terraform Enterprise.

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-Bzyc2JuegvVLAibn",
      "created-at": "2021-08-30T18:09:57.561Z",
      "email": "user@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-Bzyc2JuegvVLAibn",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  },
  "included": [
    {
      "id": "org-Bzyc2JuegvVLAibn",
      "type": "entitlement-sets",
      "attributes": {
        "cost-estimation": false,
        "configuration-designer": true,
        "operations": true,
        "private-module-registry": true,
        "sentinel": false,
        "run-tasks": false,
        "state-storage": true,
        "teams": false,
        "vcs-integrations": true,
        "usage-reporting": false,
        "user-limit": 5,
        "self-serve-billing": true,
        "audit-logging": false,
        "agents": false,
        "sso": false
      },
      "links": {
        "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
      }
    }
  ]
}

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-Bzyc2JuegvVLAibn",
      "created-at": "2021-08-30T18:09:57.561Z",
      "email": "user@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-Bzyc2JuegvVLAibn",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  },
  "included": [
    {
      "id": "org-Bzyc2JuegvVLAibn",
      "type": "entitlement-sets",
      "attributes": {
        "cost-estimation": false,
        "configuration-designer": true,
        "operations": true,
        "private-module-registry": true,
        "sentinel": false,
        "run-tasks": false,
        "state-storage": true,
        "teams": false,
        "vcs-integrations": true,
        "usage-reporting": false,
        "user-limit": 5,
        "self-serve-billing": true,
        "audit-logging": false,
        "agents": false,
        "sso": false
      },
      "links": {
        "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
      }
    }
  ]
}

»Update an Organization

PATCH /organizations/:organization_name

Parameter	Description
`:organization_name`	The name of the organization to update

Status	Response	Reason
200	JSON API document (`type: "organizations"`)	The organization was successfully updated
404	JSON API error object	Organization not found or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

»Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Key path	Type	Default	Description
`data.type`	string		Must be `"organizations"`
`data.attributes.name`	string		Name of the organization
`data.attributes.email`	string		Admin email address
`data.attributes.session-timeout`	integer	20160	Session timeout after inactivity (minutes)
`data.attributes.session-remember`	integer	20160	Session expiration (minutes)
`data.attributes.collaborator-auth-policy`	string	password	Authentication policy (`password` or `two_factor_mandatory`)
`data.attributes.cost-estimation-enabled`	boolean	true	Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to true. In a Terraform Cloud organization that does not have Teams & Governance features, this value is always false and cannot be changed. In Terraform Enterprise, Cost Estimation must also be enabled in Site Administration.
`data.attributes.send-passing-statuses-for-untriggered-speculative-plans`	boolean	false	Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration.
`data.attributes.owners-team-saml-role-id`	string	(nothing)	Optional. SAML only The name of the "owners" team
`data.attributes.assessments-enforced`	boolean	(false)	Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. Not available in Terraform Enterprise.

»Sample Payload

{
  "data": {
    "type": "organizations",
    "attributes": {
      "email": "admin@example.com"
    }
  }
}

{
  "data": {
    "type": "organizations",
    "attributes": {
      "email": "admin@example.com"
    }
  }
}

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/hashicorp

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/hashicorp

»Sample Response

Note: The two-factor-conformant and assessments-enforced properties are only returned from Terraform Cloud organizations.

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-Bzyc2JuegvVLAibn",
      "created-at": "2021-08-30T18:09:57.561Z",
      "email": "admin@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-Bzyc2JuegvVLAibn",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  }
}

{
  "data": {
    "id": "hashicorp",
    "type": "organizations",
    "attributes": {
      "external-id": "org-Bzyc2JuegvVLAibn",
      "created-at": "2021-08-30T18:09:57.561Z",
      "email": "admin@example.com",
      "session-timeout": null,
      "session-remember": null,
      "collaborator-auth-policy": "password",
      "plan-expired": false,
      "plan-expires-at": null,
      "plan-is-trial": false,
      "plan-is-enterprise": false,
      "cost-estimation-enabled": false,
      "send-passing-statuses-for-untriggered-speculative-plans": false,
      "name": "hashicorp",
      "permissions": {
        "can-update": true,
        "can-destroy": true,
        "can-access-via-teams": true,
        "can-create-module": true,
        "can-create-team": false,
        "can-create-workspace": true,
        "can-manage-users": true,
        "can-manage-subscription": true,
        "can-manage-sso": false,
        "can-update-oauth": true,
        "can-update-sentinel": false,
        "can-update-ssh-keys": true,
        "can-update-api-token": true,
        "can-traverse": true,
        "can-start-trial": true,
        "can-update-agent-pools": false,
        "can-manage-tags": true,
        "can-manage-public-modules": true,
        "can-manage-public-providers": false,
        "can-manage-run-tasks": false,
        "can-read-run-tasks": false,
        "can-create-provider": false
      },
      "fair-run-queuing-enabled": true,
      "saml-enabled": false,
      "owners-team-saml-role-id": null,
      "two-factor-conformant": false,
      "assessments-enforced": false
    },
    "relationships": {
      "oauth-tokens": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/oauth-tokens"
        }
      },
      "authentication-token": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/authentication-token"
        }
      },
      "entitlement-set": {
        "data": {
          "id": "org-Bzyc2JuegvVLAibn",
          "type": "entitlement-sets"
        },
        "links": {
          "related": "/api/v2/organizations/hashicorp/entitlement-set"
        }
      },
      "subscription": {
        "links": {
          "related": "/api/v2/organizations/hashicorp/subscription"
        }
      }
    },
    "links": {
      "self": "/api/v2/organizations/hashicorp"
    }
  }
}

»Destroy an Organization

DELETE /organizations/:organization_name

Parameter	Description
`:organization_name`	The name of the organization to destroy

Status	Response	Reason
204		The organization was successfully destroyed
404	JSON API error object	Organization not found or user unauthorized to perform action

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/hashicorp

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/organizations/hashicorp

»Sample Response

The response body will be empty if successful.

»Show the Entitlement Set

This endpoint shows the entitlements for an organization.

GET /organizations/:organization_name/entitlement-set

Parameter	Description
`:organization_name`	The name of the organization's entitlement set to view

Status	Response	Reason
200	JSON API document (`type: "entitlement-sets"`)	The request was successful
404	JSON API error object	Organization not found or user unauthorized to perform action

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set

»Sample Response

{
  "data": {
    "id": "org-Bzyc2JuegvVLAibn",
    "type": "entitlement-sets",
    "attributes": {
      "cost-estimation": false,
      "configuration-designer": true,
      "operations": true,
      "private-module-registry": true,
      "sentinel": false,
      "run-tasks": false,
      "state-storage": true,
      "teams": false,
      "vcs-integrations": true,
      "usage-reporting": false,
      "user-limit": 5,
      "self-serve-billing": true,
      "audit-logging": false,
      "agents": false,
      "sso": false
    },
    "links": {
      "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
    }
  }
}

{
  "data": {
    "id": "org-Bzyc2JuegvVLAibn",
    "type": "entitlement-sets",
    "attributes": {
      "cost-estimation": false,
      "configuration-designer": true,
      "operations": true,
      "private-module-registry": true,
      "sentinel": false,
      "run-tasks": false,
      "state-storage": true,
      "teams": false,
      "vcs-integrations": true,
      "usage-reporting": false,
      "user-limit": 5,
      "self-serve-billing": true,
      "audit-logging": false,
      "agents": false,
      "sso": false
    },
    "links": {
      "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
    }
  }
}

»Show Module Producers

Note: This endpoint is not available on Terraform Cloud.

This endpoint shows organizations that are configured to share modules with an organization through Module Sharing.

GET /organizations/:organization_name/relationships/module-producers

Parameter	Description
`:organization_name`	The name of the organization's module producers to view

Status	Response	Reason
200	JSON API document (`type: "organizations"`)	The request was successful
404	JSON API error object	Organization not found or user unauthorized to perform action

»Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 module producers per page.

»Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers

»Sample Response

{
  "data": [
    {
      "id": "hc-nomad",
      "type": "organizations",
      "attributes": {
        "name": "hc-nomad",
        "external-id": "org-ArQSQMAkFQsSUZjB"
      },
      "links": {
        "self": "/api/v2/organizations/hc-nomad"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

{
  "data": [
    {
      "id": "hc-nomad",
      "type": "organizations",
      "attributes": {
        "name": "hc-nomad",
        "external-id": "org-ArQSQMAkFQsSUZjB"
      },
      "links": {
        "self": "/api/v2/organizations/hc-nomad"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Resource Name	Description
`entitlement_set`	The entitlement set that determines which Terraform Cloud features the organization can use.

»Relationships

The following relationships may be present in various responses.

Resource Name	Description
`module-producers`	Other organizations configured to share modules with the organization.
`oauth-tokens`	OAuth tokens associated with VCS configurations for the organization.
`authentication-token`	The API token for an organization.
`entitlement-set`	The entitlement set that determines which Terraform Cloud features the organization can use.
`subscription`	The current subscription for an organization.

Terraform Cloud

Other Docs

»Organizations API

»List Organizations

»Query Parameters

»Sample Request

»Sample Response

»Show an Organization

»Sample Request

»Sample Response

»Create an Organization

»Request Body

»Sample Payload

»Sample Request

»Sample Response

»Update an Organization

»Request Body

»Sample Payload

»Sample Request

»Sample Response

»Destroy an Organization

»Sample Request

»Sample Response

»Show the Entitlement Set

»Sample Request

»Sample Response

»Show Module Producers

»Query Parameters

»Sample Request

»Sample Response

»Available Related Resources

»Relationships