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 |
---|---|
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
Sample Response
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
Sample Response
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 |
Sample Payload
Sample Request
Sample Response
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 |
Sample Payload
Sample Request
Sample Response
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
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
Sample Response
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
Sample Response
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 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. |