A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Organizations APIThe Organizations API is used to list, show, create, update, and destroy organizations.
» List OrganizationsGET /organizations
» Query ParametersThis 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 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 Requestcurl \
--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{
"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
} ,
"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
} ,
"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
} ,
"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
} ,
"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 OrganizationGET /organizations/:organization_name
Parameter Description :organization_name
The name of the organization to show
» Sample Requestcurl \
--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{
"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
} ,
"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
} ,
"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 OrganizationPOST /organizations
» Request BodyThis 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
» Sample Payload{
"data" : {
"type" : "organizations" ,
"attributes" : {
"name" : "hashicorp" ,
"email" : "user@example.com"
}
}
}
{
"data" : {
"type" : "organizations" ,
"attributes" : {
"name" : "hashicorp" ,
"email" : "user@example.com"
}
}
}
» Sample Requestcurl \
--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{
"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
} ,
"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
} ,
"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 OrganizationPATCH /organizations/:organization_name
Parameter Description :organization_name
The name of the organization to update
» Request BodyThis 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
» Sample Payload{
"data" : {
"type" : "organizations" ,
"attributes" : {
"email" : "admin@example.com"
}
}
}
{
"data" : {
"type" : "organizations" ,
"attributes" : {
"email" : "admin@example.com"
}
}
}
» Sample Requestcurl \
--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{
"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
} ,
"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
} ,
"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 OrganizationDELETE /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 Requestcurl \
--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 ResponseThe response body will be empty if successful.
» Show the Entitlement SetThis 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
» Sample Requestcurl \
--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 ProducersNote: 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
» Query ParametersThis 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 Requestcurl \
--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.
» RelationshipsThe 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.