The Organizations API is used to list, show, create, update, and destroy organizations.
GET /organizations
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 Descriptionq 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
Note: Only HCP Terraform organizations return the two-factor-conformant and assessments-enforced properties.
{
"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,
"aggregated-commit-status-enabled": false,
"speculative-plan-management-enabled": true,
"allow-force-delete-workspaces": 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,
"can-create-project": true
},
"fair-run-queuing-enabled": true,
"saml-enabled": false,
"owners-team-saml-role-id": null,
"two-factor-conformant": false,
"assessments-enforced": false,
"default-execution-mode": "remote"
},
"relationships": {
"default-agent-pool": {
"data": null
},
"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,
"aggregated-commit-status-enabled": true,
"speculative-plan-management-enabled": true,
"allow-force-delete-workspaces": 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,
"can-create-project": false
},
"fair-run-queuing-enabled": true,
"saml-enabled": false,
"owners-team-saml-role-id": null,
"two-factor-conformant": false,
"assessments-enforced": false,
"default-execution-mode": "remote"
},
"relationships": {
"default-agent-pool": {
"data": null
},
"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
}
}
}
GET /organizations/:organization_name
:organization_name The name of the organization to show Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/organizations/hashicorp
Note: Only HCP Terraform organizations return the two-factor-conformant and assessments-enforced properties.
{
"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,
"aggregated-commit-status-enabled": true,
"speculative-plan-management-enabled": true,
"allow-force-delete-workspaces": 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,
"can-create-project": true
},
"fair-run-queuing-enabled": true,
"saml-enabled": false,
"owners-team-saml-role-id": null,
"two-factor-conformant": false,
"assessments-enforced": false,
"default-execution-mode": "remote"
},
"relationships": {
"default-agent-pool": {
"data": null
},
"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"
}
}
}
POST /organizations
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 Descriptiondata.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 false Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation 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.aggregated-commit-status-enabled boolean true Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to true. You cannot use this option if send-passing-statuses-for-untriggered-speculative-plans is set to true. data.attributes.speculative-plan-management-enabled boolean true Whether or not to enable Automatically cancel plan-only runs. Defaults to true. 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. data.attributes.allow-force-delete-workspaces boolean (false) Whether workspace administrators can delete workspaces with resources under management. If false, only organization owners may delete these workspaces. data.attributes.default-execution-mode string remote Which execution mode to use by default. Valid values are remote, local, and agent. data.attributes.default-agent-pool-id string (previous value) Required when default-execution-mode is set to agent. The ID of the agent pool belonging to the organization. Do not specify this value if you set execution-mode to remote or local. data.attributes.enforce-hyok boolean false Whether or not new workspaces within the organization are created with hold your own key enabled. Your organization must have a primary HYOK configuration before enabling enforce-hyok. Hold your own key is only available in HCP Terraform, learn more. Sample Payload
{
"data": {
"type": "organizations",
"attributes": {
"name": "hashicorp",
"email": "user@example.com"
}
}
}
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/organizations
Note: Only HCP Terraform organizations return the two-factor-conformant and assessments-enforced properties.
{
"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,
"aggregated-commit-status-enabled": true,
"speculative-plan-management-enabled": true,
"allow-force-delete-workspaces": 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,
"can-create-project": true
},
"fair-run-queuing-enabled": true,
"saml-enabled": false,
"owners-team-saml-role-id": null,
"two-factor-conformant": false,
"assessments-enforced": false,
"default-execution-mode": "remote"
},
"relationships": {
"default-agent-pool": {
"data": null
},
"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": {
"agents": false,
"audit-logging": false,
"configuration-designer": true,
"cost-estimation": false,
"global-run-tasks": false,
"module-tests-generation": false,
"operations": true,
"policy-enforcement": false,
"policy-limit": null,
"policy-mandatory-enforcement-limit": null,
"policy-set-limit": null,
"private-module-registry": true,
"run-task-limit": null,
"run-task-mandatory-enforcement-limit": null,
"run-task-workspace-limit": null,
"run-tasks": false,
"self-serve-billing": true,
"sentinel": false,
"sso": false,
"state-storage": true,
"teams": false,
"usage-reporting": false,
"user-limit": 5,
"vcs-integrations": true,
"versioned-policy-set-limit": null
},
"links": {
"self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
}
}
]
}
PATCH /organizations/:organization_name
:organization_name The name of the organization to update Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Key path Type Default Descriptiondata.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 false Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation 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.aggregated-commit-status-enabled boolean true Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to true. You cannot use this option if send-passing-statuses-for-untriggered-speculative-plans is set to true. data.attributes.speculative-plan-management-enabled boolean true Whether or not to enable Automatically cancel plan-only runs. Defaults to true. 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. data.attributes.allow-force-delete-workspaces boolean false Whether workspace administrators can delete workspaces with resources under management. If false, only organization owners may delete these workspaces. data.attributes.default-execution-mode string remote Which execution mode to use by default. Valid values are remote, local, and agent. data.attributes.default-agent-pool-id string (previous value) Required when default-execution-mode is set to agent. The ID of the agent pool belonging to the organization. Do not specify this value if you set execution-mode to remote or local. data.attributes.enforce-hyok boolean false Whether or not new workspaces within the organization are created with hold your own key (HYOK) enabled. Your organization must have a primary HYOK configuration before enabling enforce-hyok. Hold your own key is only available in HCP Terraform, learn more. Sample Payload
{
"data": {
"type": "organizations",
"attributes": {
"email": "admin@example.com"
}
}
}
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
Note: The two-factor-conformant and assessments-enforced properties are only returned from HCP Terraform 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,
"aggregated-commit-status-enabled": true,
"speculative-plan-management-enabled": true,
"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,
"can-create-project": true
},
"fair-run-queuing-enabled": true,
"saml-enabled": false,
"owners-team-saml-role-id": null,
"two-factor-conformant": false,
"assessments-enforced": false,
"default-execution-mode": "remote"
},
"relationships": {
"default-agent-pool": {
"data": null
},
"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"
}
}
}
DELETE /organizations/:organization_name
: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
The response body will be empty if successful.
This endpoint shows the entitlements for an organization.
GET /organizations/:organization_name/entitlement-set
:organization_name The name of the organization's entitlement set to view Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set
{
"data": {
"id": "org-Bzyc2JuegvVLAibn",
"type": "entitlement-sets",
"attributes": {
"agents": false,
"audit-logging": false,
"configuration-designer": true,
"cost-estimation": false,
"global-run-tasks": false,
"module-tests-generation": false,
"operations": true,
"policy-enforcement": false,
"policy-limit": 5,
"policy-mandatory-enforcement-limit": null,
"policy-set-limit": 1,
"private-module-registry": true,
"private-policy-agents": false,
"private-run-tasks": true,
"private-vcs": false,
"run-task-limit": 1,
"run-task-mandatory-enforcement-limit": 1,
"run-task-workspace-limit": 10,
"run-tasks": false,
"self-serve-billing": true,
"sentinel": false,
"sso": false,
"state-storage": true,
"teams": false,
"usage-reporting": false,
"user-limit": 5,
"vcs-integrations": true,
"versioned-policy-set-limit": null
},
"links": {
"self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn"
}
}
}
The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:
entitlement_set The entitlement set that determines which HCP Terraform features the organization can use.
The following relationships may be present in various responses.
Resource Name Descriptionmodule-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 HCP Terraform features the organization can use. subscription The current subscription for an organization. default-agent-pool An organization's default agent pool. Set this value if your default-execution-mode is agent. data-retention-policy Enterprise Enterprise Specifies an organization's data retention policy. Refer to Data Retention Policy APIs in the Terraform Enterprise documentation for more details.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4