Provider sets API reference

Note

This feature is currently in beta. Do not use beta functionality in production environments.

You can create sets of reusable provider block configurations and apply them to multiple no-code workspaces. When you apply the set, it inserts the provider block into the configuration, letting HCP Terraform organization administrators enforce best practices. Provider sets also let you deploy standard Terraform modules as no-code modules. Refer to Configure provider sets for more information.

Overview

The scope of the API includes the following endpoints:

Method	Path	Action
`POST`	`/organizations/:organization-name/provider-sets`	Call this endpoint to create a provider set.
`GET`	`/organizations/:organization-name/provider-sets/`	Call this endpoint to list provider sets.
`GET`	`/provider-sets/:provider-set-id`	Call this endpoint to show a provider set.
`PATCH`	`/provider-sets/:provider-set-id`	Call this endpoint to update a provider set.
`DELETE`	`/provider-sets/:provider-set-id`	Call this endpoint to delete a provider set.

Requirements

The API token you use to manage provider sets must have the Manage all projects and Manage all workspaces permissions. Refer to Permissions for additional information.

Create a provider set

POST /organizations/:organization_name/provider-sets

This endpoint creates a new provider set in the specified organization.

Request body

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"provider-sets"`.
`data.attributes.name`	string		The name of the provider set.
`data.attributes.description`	string	`""`	Text displayed in the UI to contextualize the provider set and its purpose.
`data.attributes.provider-source`	string		The fully qualified provider source to download, verify, and configure the correct provider at runtime, for example `"registry.terraform.io/hashicorp/aws"`.
`data.attributes.global`	boolean	false	If `true`, the provider set applies to every no-code workspace in the organization. Otherwise, it only applies to associated projects.
`data.attributes.priority`	boolean	false	If `true`, this configuration overrides any standard-priority configurations set at the project or workspace level.
`data.attributes.configuration-hcl`	string		The HCL configuration for the provider.
`data.relationships.workspaces.data[]`	array(object)	`[]`	A list of workspaces to associate the provider set with. You can only specify this attribute when `data.attributes.global` is `false`.
`data.relationships.workspaces.data[].type`	string		Must be `"workspaces"`.
`data.relationships.workspaces.data[].id`	string		The workspace ID to associate the provider set with.
`data.relationships.projects.data[]`	array(object)	`[]`	A list of projects to associate the provider set with. You can only specify this attribute when `data.attributes.global` is `false`.
`data.relationships.projects.data[].type`	string		Must be `"projects"`.
`data.relationships.projects.data[].id`	string		The project ID to associate the provider set with.

Status	Response	Reason
201	JSON API document	Successfully created the provider set.
404	JSON API error object	Not found, or the user is unauthorized to perform this action.
422	JSON API error object	Malformed request body, such as missing attributes, and wrong types.
500	JSON API error object	Internal system failure.

Sample payload

{
  "data": {
    "type": "provider-sets",
    "attributes": {
      "name": "aws-east",
      "description": "Deploy to AWS us-east-2",
      "provider-source": "registry.terraform.io/hashicorp/aws",
      "global": false,
      "priority": false,
      "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-2\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "projects": {
        "data": [
          {
            "id": "prj-FfTE11pvSzKu6Gkq",
            "type": "projects"
          }
        ]
      }
    }
  }
}

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/my-organization/provider-sets

Sample response

{
  "data": {
    "id": "provset-gzW6dM4VVbowrFTv",
    "type": "provider-sets",
    "attributes": {
      "name": "aws-east",
      "description": "Deploy to AWS us-east-2",
      "global": false,
      "updated-at": "2026-09-25T16:33:29.532Z",
      "created-at": "2026-09-25T16:33:29.532Z",
      "provider-source": "registry.terraform.io/hashicorp/aws",
      "priority": false,
      "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-2\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "workspaces": {
        "data": []
      },
      "projects": {
        "data": [
          {
            "id": "prj-FfTE11pvSzKu6Gkq",
            "type": "projects"
          }
        ]
      }
    }
  }
}

List provider sets

List all provider sets for an organization.

GET /organizations/:organization_name/provider-sets

Parameter	Description
`:organization_name`	The name of the organization the provider sets belong to

Query Parameters

All list endpoints support pagination with standard URL query parameters and searching with the q parameter. 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 returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 provider sets per page.
`q`	Optional. A search query string. You can search for a provider set using its name.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/provider-sets

Sample response

{
  "data": [
    {
      "id": "provset-gzW6dM4VVbowrFTv",
      "type": "provider-sets",
      "attributes": {
        "name": "aws-east",
        "description": "Deploy to AWS us-east-2",
        "global": false,
        "updated-at": "2026-09-25T16:33:29.532Z",
        "created-at": "2026-09-25T16:33:29.532Z",
        "provider-source": "registry.terraform.io/hashicorp/aws",
        "priority": false,
        "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-2\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        },
        "workspaces": {
          "data": []
        },
        "projects": {
          "data": [
            {
              "id": "prj-FfTE11pvSzKu6Gkq",
              "type": "projects"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/provider-sets?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/provider-sets?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/provider-sets?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": 1
    }
  }
}

Show a provider set

GET /provider-sets/:provider-set-id

This endpoint returns details of the specified provider set.

Parameter	Description
`:provider-set-id`	The ID of the provider set to show.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/provider-sets/provset-gzW6dM4VVbowrFTv

Sample response

{
  "data": {
    "id": "provset-gzW6dM4VVbowrFTv",
    "type": "provider-sets",
    "attributes": {
      "name": "aws-east",
      "description": "Deploy to AWS us-east-2",
      "global": false,
      "updated-at": "2026-09-25T16:33:29.532Z",
      "created-at": "2026-09-25T16:33:29.532Z",
      "provider-source": "registry.terraform.io/hashicorp/aws",
      "priority": false,
      "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-2\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "workspaces": {
        "data": []
      },
      "projects": {
        "data": [
          {
            "id": "prj-FfTE11pvSzKu6Gkq",
            "type": "projects"
          }
        ]
      }
    }
  }
}

Update a provider set

PATCH /provider-sets/:provider-set-id

This endpoint updates the specified provider set configuration.

Parameter	Description
`:provider-set-id`	The ID of the provider set to update.

Request body

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"provider-sets"`.
`data.attributes.name`	string	(previous value)	The name of the provider set.
`data.attributes.description`	string	(previous value)	Text displayed in the UI to contextualize the provider set and its purpose.
`data.attributes.provider-source`	string	(previous value)	The fully qualified provider source to download, verify, and configure the correct provider at runtime, for example `"registry.terraform.io/hashicorp/aws"`.
`data.attributes.global`	boolean	(previous value)	If `true`, the provider set applies to every no-code workspace in the organization. Otherwise, it only applies to associated projects.
`data.attributes.priority`	boolean	(previous value)	If `true`, this configuration overrides any standard-priority configurations set at the project or workspace level.
`data.attributes.configuration-hcl`	string	(previous value)	The HCL configuration for the provider.
`data.relationships.workspaces.data[]`	array(object)	`[]`	A list of workspaces to associate the provider set with. You can only specify this attribute when `data.attributes.global` is `false`.
`data.relationships.workspaces.data[].type`	string		Must be `"workspaces"`.
`data.relationships.workspaces.data[].id`	string		The workspace ID to associate the provider set with.
`data.relationships.projects.data[]`	array(object)	`[]`	A list of projects to associate the provider set with. You can only specify this attribute when `data.attributes.global` is `false`.
`data.relationships.projects.data[].type`	string		Must be `"projects"`.
`data.relationships.projects.data[].id`	string		The project ID to associate the provider set with.

Status	Response	Reason(s)
200	JSON API document	Successfully updated provider set
404	JSON API error object	Organization or provider set not found, or user unauthorized to perform action
422	JSON API error object	Problem with payload or request. Details provided in the error object

Sample payload

{
  "data": {
    "type": "provider-sets",
    "attributes": {
      "description": "Deploy to AWS us-east-1",
      "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-1\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
    }
  }
}

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/provider-sets/provset-gzW6dM4VVbowrFTv

Sample response

{
  "data": {
    "id": "provset-gzW6dM4VVbowrFTv",
    "type": "provider-sets",
    "attributes": {
      "name": "aws-east",
      "description": "Deploy to AWS us-east-1",
      "global": false,
      "updated-at": "2026-09-25T16:36:50.528Z",
      "created-at": "2026-09-25T16:33:29.532Z",
      "provider-source": "registry.terraform.io/hashicorp/aws",
      "priority": false,
      "configuration-hcl": "provider \"aws\" {\n  region = \"us-east-1\"\n default_tags {\n    tags = {\n      Environment = \"production\"\n      ManagedBy   = \"terraform\"\n    }\n  }\n}\n"
    },
    "relationships": {
      "organization": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "workspaces": {
        "data": []
      },
      "projects": {
        "data": [
          {
            "id": "prj-FfTE11pvSzKu6Gkq",
            "type": "projects"
          }
        ]
      }
    }
  }
}

Delete a provider set

DELETE /provider-sets/:provider-set-id

This endpoint deletes the specified provider set.

Parameter	Description
`:provider-set-id`	The ID of the provider set to delete.

Status	Response	Reason
204	No Content	Successfully deleted the provider set
404	JSON API error object	Provider set 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/provider-sets/provset-gzW6dM4VVbowrFTv

On success, this endpoint responds with no content.