HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

Organizations API reference

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

List Organizations

GET /organizations

StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization 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.

ParameterDescription
qOptional. 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

Sample Response

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
    }
  }
}

Show an Organization

GET /organizations/:organization_name

ParameterDescription
:organization_nameThe name of the organization to show
StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization 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

Sample Response

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"
    }
  }
}

Create an Organization

POST /organizations

StatusResponseReason
201JSON API document (type: "organizations")The organization was successfully created
404JSON API error objectOrganization not found or user unauthorized to perform action
422JSON API error objectMalformed 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 pathTypeDefaultDescription
data.typestringMust be "organizations"
data.attributes.namestringName of the organization
data.attributes.emailstringAdmin email address
data.attributes.session-timeoutinteger20160Session timeout after inactivity (minutes)
data.attributes.session-rememberinteger20160Session expiration (minutes)
data.attributes.collaborator-auth-policystringpasswordAuthentication policy (password or two_factor_mandatory)
data.attributes.cost-estimation-enabledbooleanfalseWhether 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-plansbooleanfalseWhether 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-enabledbooleantrueWhether 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-enabledbooleantrueWhether or not to enable Automatically cancel plan-only runs. Defaults to true.
data.attributes.owners-team-saml-role-idstring(nothing)Optional. SAML only The name of the "owners" team
data.attributes.assessments-enforcedboolean(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-workspacesboolean(false)Whether workspace administrators can delete workspaces with resources under management. If false, only organization owners may delete these workspaces.
data.attributes.default-execution-modebooleanremoteWhich execution mode to use by default. Valid values are remote, local, and agent.
data.attributes.default-agent-pool-idstring(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.

Sample Payload

{
  "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

Sample Response

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"
      }
    }
  ]
}

Update an Organization

PATCH /organizations/:organization_name

ParameterDescription
:organization_nameThe name of the organization to update
StatusResponseReason
200JSON API document (type: "organizations")The organization was successfully updated
404JSON API error objectOrganization not found or user unauthorized to perform action
422JSON API error objectMalformed 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 pathTypeDefaultDescription
data.typestringMust be "organizations"
data.attributes.namestringName of the organization
data.attributes.emailstringAdmin email address
data.attributes.session-timeoutinteger20160Session timeout after inactivity (minutes)
data.attributes.session-rememberinteger20160Session expiration (minutes)
data.attributes.collaborator-auth-policystringpasswordAuthentication policy (password or two_factor_mandatory)
data.attributes.cost-estimation-enabledbooleanfalseWhether 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-plansbooleanfalseWhether 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-enabledbooleantrueWhether 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-enabledbooleantrueWhether or not to enable Automatically cancel plan-only runs. Defaults to true.
data.attributes.owners-team-saml-role-idstring(nothing)Optional. SAML only The name of the "owners" team
data.attributes.assessments-enforcedbooleanfalseWhether 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-workspacesbooleanfalseWhether workspace administrators can delete workspaces with resources under management. If false, only organization owners may delete these workspaces.
data.attributes.default-execution-modebooleanremoteWhich execution mode to use by default. Valid values are remote, local, and agent.
data.attributes.default-agent-pool-idstring(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.

Sample Payload

{
  "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

Sample Response

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"
    }
  }
}

Destroy an Organization

DELETE /organizations/:organization_name

ParameterDescription
:organization_nameThe name of the organization to destroy
StatusResponseReason
204The organization was successfully destroyed
404JSON API error objectOrganization 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

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

ParameterDescription
:organization_nameThe name of the organization's entitlement set to view
StatusResponseReason
200JSON API document (type: "entitlement-sets")The request was successful
404JSON API error objectOrganization 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

Sample Response

{
  "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-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"
    }
  }
}

Show Module Producers

Enterprise

This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform.

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

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

ParameterDescription
:organization_nameThe name of the organization's module producers to view
StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization 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.

ParameterDescription
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

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
    }
  }
}

Show data retention policy

Enterprise

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

GET /organizations/:organization_name/relationships/data-retention-policy

ParameterDescription
:organization_nameThe name of the organization to show the data retention policy for.

This endpoint shows the data retention policy set explicitly on the organization.

When no data retention policy is set for the organization, the endpoint returns the default policy configured for the Terraform Enterprise installation. Read more about organization data retention policies.

For additional information, refer to Data Retention Policy Types in the Terraform Enterprise documentation.

Create or update data retention policy

Enterprise

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

POST /organizations/:organization_name/relationships/data-retention-policy

ParameterDescription
:organization_nameThe name of the organization to update the data retention policy for.

This endpoint creates a data retention policy for an organization or updates the existing policy.

Read more about organization data retention policies.

Refer to Data Retention Policy API in the Terraform Enterprise documentation for details.

Remove data retention policy

Enterprise

This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform.

DELETE /organizations/:organization_name/relationships/data-retention-policy

ParameterDescription
:organization_nameThe name of the organization to remove the data retention policy for.

This endpoint removes the data retention policy explicitly set on an organization. When the data retention policy is deleted, the organization inherits the default policy configured for the Terraform Enterprise installation. Refer to Data Retention Policies for additional information.

Refer to Data Retention Policies for information about configuring data retention policies for an organization.

Refer to Data Retention Policy API in the Terraform Enterprise documentation for details.

Available Related Resources

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

Resource NameDescription
entitlement_setThe entitlement set that determines which HCP Terraform features the organization can use.

Relationships

The following relationships may be present in various responses.

Resource NameDescription
module-producersOther organizations configured to share modules with the organization.
oauth-tokensOAuth tokens associated with VCS configurations for the organization.
authentication-tokenThe API token for an organization.
entitlement-setThe entitlement set that determines which HCP Terraform features the organization can use.
subscriptionThe current subscription for an organization.
default-agent-poolAn organization's default agent pool. Set this value if your default-execution-mode is agent.
data-retention-policyEnterprise Specifies an organization's data retention policy. Refer to Data Retention Policy APIs in the Terraform Enterprise documentation for more details.
Edit this page on GitHub