HashiConf 2024 Now streaming live from Boston! Attend for free
Terraform
Terraform Home

Admin Organizations API

Terraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.

The Organizations Admin API contains endpoints to help site administrators manage organizations.

List all Organizations

GET /api/v2/admin/organizations

This endpoint lists all organizations in the Terraform Enterprise installation.

StatusResponseReason
200JSON API document (type: "organizations")Successfully listed organizations
404JSON API error objectClient is not an administrator.

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
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.
filter[module_producer]Optional. Allows filtering organizations based on their module sharing configuration. Accepts a boolean true/false value. A true value returns organizations that are configured to share their modules, and a false value returns organizations that are not configured to share their modules.
filter[provider_producer]Optional. Allows filtering organizations based on their provider sharing configuration. Accepts a boolean true/false value. A true value returns organizations that are configured to share their providers, and a false value returns organizations that are not configured to share their providers.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 organizations per page.

Available Related Resources

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

Resource NameDescription
ownersA list of owners for each organization.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "my-organization",
      "type": "organizations",
      "attributes": {
        "access-beta-tools": false,
        "external-id": "org-XBiRp755dav5p3P2",
        "is-disabled": false,
        "name": "my-organization",
        "apply-timeout": null,
        "plan-timeout": null,
        "terraform-worker-sudo-enabled": false,
        "notification-email": "my-organization@example.com",
        "global-module-sharing": false,
        "global-provider-sharing": false,
        "sso-enabled": false,
        "workspace-limit": null
      },
      "relationships": {
        "owners": {
          "data": [
            {
              "id": "user-hxTQDETqnJsi5VYP",
              "type": "users"
            }
          ]
        },
        "subscription": {
          "data": null
        },
        "feature-set": {
          "data": null
        },
        "module-consumers": {
          "links": {
            "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers"
          }
        }
      },
      "links": {
        "self": "/api/v2/admin/organizations/my-organization"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://tfe.example.com/api/v2/admin/organizations?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
  },
  "meta": {
    "status-counts": {
      "total": 1,
      "active": 1,
      "disabled": 0
    },
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show an Organization

GET /api/v2/admin/organizations/:name

ParameterDescription
:nameThe name of the organization to show
StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization not found, or client is not an administrator

Available Related Resources

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

Resource NameDescription
ownersA list of owners for the organization.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/admin/organizations/my-organization

Sample Response

{
  "data": {
    "id": "my-organization",
    "type": "organizations",
    "attributes": {
      "access-beta-tools": false,
      "external-id": "org-XBiRp755dav5p3P2",
      "is-disabled": false,
      "name": "my-organization",
      "apply-timeout": null,
      "plan-timeout": null,
      "terraform-worker-sudo-enabled": false,
      "notification-email": "my-organization@example.com",
      "global-module-sharing": false,
      "global-provider-sharing": false,
      "sso-enabled": false,
      "workspace-limit": null
    },
    "relationships": {
      "owners": {
        "data": [
          {
            "id": "user-hxTQDETqnJsi5VYP",
            "type": "users"
          }
        ]
      },
      "subscription": {
        "data": null
      },
      "feature-set": {
        "data": null
      },
      "module-consumers": {
        "links": {
          "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers"
        }
      }
    },
    "links": {
      "self": "/api/v2/admin/organizations/my-organization"
    }
  }
}

Update an Organization

PATCH /admin/organizations/:name

ParameterDescription
: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. Note that the Admin Organizations API may offer a different set of attributes than the Organizations API.

Key pathTypeDefaultDescription
data.typestringMust be "organizations"
data.attributes.access-beta-toolsbooleanfalseWhether or not workspaces in the organization can be configured to use beta Terraform versions.
data.attributes.global-module-sharingbooleanfalseIf true, modules in the organization's private module repository will be available to all other organizations in this Terraform Enterprise instance. Enabling this will disable any previously configured module consumers.
data.attributes.global-provider-sharingbooleanfalseIf true, providers in the organization's private provider repository will be available to all other organizations in this Terraform Enterprise instance. Enabling this will disable any previously configured provider consumers.
data.attributes.is-disabledbooleanfalseRemoves all permissions from the organization and makes it inaccessible to users.
data.attributes.apply-timeoutstring24hMaximum run time for Terraform applies for this organization. Will use the configured global defaults if left unset. Specify a duration with a decimal number and a unit suffix.
data.attributes.plan-timeoutstring2hMaximum run time for Terraform plans for this organization. Will use the configured global defaults if left unset. Specify a duration with a decimal number and a unit suffix.
data.attributes.terraform-build-worker-apply-timeoutstring24hDeprecated. Please use data.attributes.apply-timeout instead.
data.attributes.terraform-build-worker-plan-timeoutstring2hDeprecated. Please use data.attributes.plan-timeout instead.
data.attributes.workspace-limitintegerMaximum number of workspaces for this organization. If this number is set to a value lower than the number of workspaces the organization has, it will prevent additional workspaces from being created, but existing workspaces will not be affected. If set to 0, this limit will have no effect.

Sample Payload

{
  "data": {
    "type": "organizations",
    "attributes": {
      "global-module-sharing": true
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/organizations/my-organization

Sample Response

{
  "data": {
    "id": "my-organization",
    "type": "organizations",
    "attributes": {
      "access-beta-tools": false,
      "external-id": "org-XBiRp755dav5p3P2",
      "is-disabled": false,
      "name": "my-organization",
      "apply-timeout": null,
      "plan-timeout": null,
      "terraform-worker-sudo-enabled": false,
      "notification-email": "my-organization@example.com",
      "global-module-sharing": true,
      "global-provider-sharing": false,
      "sso-enabled": false,
      "workspace-limit": null
    },
    "relationships": {
      "owners": {
        "data": [
          {
            "id": "user-hxTQDETqnJsi5VYP",
            "type": "users"
          }
        ]
      },
      "subscription": {
        "data": null
      },
      "feature-set": {
        "data": null
      },
      "module-consumers": {
        "links": {
          "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers"
        }
      }
    },
    "links": {
      "self": "/api/v2/admin/organizations/my-organization"
    }
  }
}

Delete an Organization

DELETE /admin/organizations/:name

ParameterDescription
:nameThe name of the organization to delete
StatusResponseReason
204Empty responseThe organization was successfully deleted
404JSON API error objectOrganization not found, or client is not an administrator

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://tfe.example.com/api/v2/admin/organizations/my-organization

List Module Consumers for an Organization

This API endpoint is available in Terraform Enterprise as of version 202103-1.

GET /api/v2/admin/organizations/:name/relationships/module-consumers

This endpoint lists specific organizations in the Terraform Enterprise installation that have permission to use an organization's modules. It will be empty if the organization is sharing modules using global module sharing, or if the organization has no module sharing configuration.

ParameterDescription
:nameThe name of the organization whose module consumers should be listed
StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization not found, or client is not an administrator

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 organizations per page.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "my-organization",
      "type": "organizations",
      "attributes": {
        "access-beta-tools": false,
        "external-id": "org-XBiRp755dav5p3P2",
        "is-disabled": false,
        "name": "my-organization",
        "apply-timeout": null,
        "plan-timeout": null,
        "terraform-worker-sudo-enabled": false,
        "notification-email": "my-organization@example.com",
        "global-module-sharing": false,
        "global-provider-sharing": false,
        "sso-enabled": false,
        "workspace-limit": null
      },
      "relationships": {
        "module-consumers": {
          "links": {
            "related": "/api/v2/admin/organizations/my-organization/relationships/module-consumers"
          }
        },
        "owners": {
          "data": [
            {
              "id": "user-hxTQDETqnJsi5VYP",
              "type": "users"
            }
          ]
        },
        "subscription": {
          "data": null
        },
        "feature-set": {
          "data": null
        }
      },
      "links": {
        "self": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers?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
        }
      }
    }
  ]
}

Update an Organization's Module Consumers

This API endpoint is available in Terraform Enterprise as of version 202103-1.

Note: This API endpoint is deprecated and will be removed in a future release. Transition existing integrations with this API to the Admin Registry Sharing API.

PATCH /admin/organizations/:name/relationships/module-consumers

This endpoint is used to specify a list of organizations that can use modules from the sharing organization's private registry. Setting a list of module consumers will turn off global module sharing for an organization.

ParameterDescription
:nameThe name of the organization whose registry is being shared
StatusResponseReason
204No contentThe list of module consumers 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, module consumer not found, etc..)

Request Body

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

Key pathTypeDefaultDescription
data[]array[object]A list of resource identifier objects that defines which organizations will consume modules. These objects must contain id and type properties, and the type property must be organizations (e.g. { "id": "an-org", "type": "organizations" }).

Sample Payload

{
  "data": [
    {
      "id": "an-org",
      "type": "organizations"

    },
    {
      "id": "another-org",
      "type": "organizations"
    }
  ]
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/module-consumers

Sample Response

The response body will be empty if successful.

List Provider Consumers for an Organization

This API endpoint is available in Terraform Enterprise as of version 202301-1.

GET /api/v2/admin/organizations/:name/relationships/provider-consumers

This endpoint lists specific organizations in the Terraform Enterprise installation that have permission to use an organization's providers. It will be empty if the organization is sharing providers using global provider sharing, or if the organization has no provider sharing configuration.

ParameterDescription
:nameThe name of the organization whose provider consumers should be listed
StatusResponseReason
200JSON API document (type: "organizations")The request was successful
404JSON API error objectOrganization not found, or client is not an administrator

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 organizations per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers

Sample Response

{
  "data": [
    {
      "id": "my-organization",
      "type": "organizations",
      "attributes": {
        "access-beta-tools": false,
        "external-id": "org-XBiRp755dav5p3P2",
        "is-disabled": false,
        "name": "my-organization",
        "apply-timeout": null,
        "plan-timeout": null,
        "terraform-worker-sudo-enabled": false,
        "notification-email": "my-organization@example.com",
        "global-module-sharing": false,
        "global-provider-sharing": false,
        "sso-enabled": false,
        "workspace-limit": null
      },
      "relationships": {
        "provider-consumers": {
          "links": {
            "related": "/api/v2/admin/organizations/my-organization/relationships/provider-consumers"
          }
        },
        "owners": {
          "data": [
            {
              "id": "user-hxTQDETqnJsi5VYP",
              "type": "users"
            }
          ]
        },
        "subscription": {
          "data": null
        },
        "feature-set": {
          "data": null
        }
      },
      "links": {
        "self": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://tfe.example.com/api/v2/admin/organizations/my-organization/relationships/provider-consumers?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
        }
      }
    }
  ]
}