A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Registry Providers APIYou can add publicly curated providers from the Terraform Registry and custom, private providers to your Terraform Cloud private registry. The private registry stores a pointer to public providers so that you can view their data from within Terraform Cloud. This lets you clearly designate all of the providers that are recommended for the organization and makes them centrally accessible.
All members of an organization can view and use both public and private providers, but you need owners team or Manage Private Registry permissions to add, update, or delete them them in private registry.
For publicly curated providers, the Terraform Cloud Registry acts as a proxy to the Terraform Registry for the following:
The public registry discovery endpoints have the path prefix provided in the discovery document which is currently /api/registry/public/v1
. Authentication is handled the same as all other Terraform Cloud endpoints.GET /organizations/:organization_name/registry-providers
» ParametersParameter Description :organization_name
The name of the organization to list available providers from.
Lists the providers included in the private registry for the specified organization.
» Query ParametersThis 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 q
Optional. A search query string. Providers are searchable by both their name and their namespace fields.filter[field name]
Optional. If specified, restricts results to those with the matching field name value. Valid values are registry_name
, and organization_name
.page[number]
Optional. If omitted, the endpoint will return the first page.page[size]
Optional. If omitted, the endpoint will return 20 registry providers per page.
» Sample Requestcurl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers
curl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers
» Sample Response{
"data" : [
{
"id" : "prov-kwt1cBiX2SdDz38w" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "my-organization" ,
"created-at" : "2021-04-07T19:01:18.528Z" ,
"updated-at" : "2021-04-07T19:01:19.863Z" ,
"registry-name" : "public" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aws"
}
} ,
{
"id" : "prov-PopQnMtYDCcd3PRX" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aurora" ,
"namespace" : "my-organization" ,
"created-at" : "2021-04-07T19:04:41.375Z" ,
"updated-at" : "2021-04-07T19:04:42.828Z" ,
"registry-name" : "public" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aurora"
}
} ,
...,
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6" ,
"first" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6" ,
"prev" : null ,
"next" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=2&page%5Bsize%5D=6" ,
"last" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=29&page%5Bsize%5D=6"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"page-size" : 6 ,
"prev-page" : null ,
"next-page" : 2 ,
"total-pages" : 29 ,
"total-count" : 169
}
}
}
{
"data" : [
{
"id" : "prov-kwt1cBiX2SdDz38w" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "my-organization" ,
"created-at" : "2021-04-07T19:01:18.528Z" ,
"updated-at" : "2021-04-07T19:01:19.863Z" ,
"registry-name" : "public" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aws"
}
} ,
{
"id" : "prov-PopQnMtYDCcd3PRX" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aurora" ,
"namespace" : "my-organization" ,
"created-at" : "2021-04-07T19:04:41.375Z" ,
"updated-at" : "2021-04-07T19:04:42.828Z" ,
"registry-name" : "public" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aurora"
}
} ,
...,
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6" ,
"first" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6" ,
"prev" : null ,
"next" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=2&page%5Bsize%5D=6" ,
"last" : "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=29&page%5Bsize%5D=6"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"page-size" : 6 ,
"prev-page" : null ,
"next-page" : 2 ,
"total-pages" : 29 ,
"total-count" : 169
}
}
}
» Create a ProviderPOST /organizations/:organization_name/registry-providers
Use this endpoint to create both public and private providers:
Public providers: The public provider record will be available in the organization's registry provider list immediately after creation. You cannot create versions for public providers; you must use the versions available on the Terraform Registry.Private providers: The private provider record will be available in the organization's registry provider list immediately after creation, but you must create a version and upload release assets before consumers can use it. The private registry does not automatically update private providers when you release new versions. You must add each new version with the Create a Provider Version endpoint.» ParametersParameter Description :organization_name
The name of the organization to create a provider in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team.
» Request BodyImportant: For private providers, you must also create a version, a platform, and upload release assets before consumers can use the provider. Refer to Publishing a Private Provider for more details.
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 "registry-providers"
. data.attributes.name
string The name of the provider. data.attributes.namespace
string The namespace of the provider. For private providers this is the same as the :organization_name
parameter. data.attributes.registry-name
string Whether this is a publicly maintained provider or private. Must be either public
or private
.
» Sample Payload (Private Provider){
"data" : {
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "private"
}
}
}
{
"data" : {
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "private"
}
}
}
» Sample Payload (Public Provider){
"data" : {
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public"
}
}
}
{
"data" : {
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public"
}
}
}
» Sample Requestcurl \
--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/registry-providers
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/registry-providers
» Sample Response (Private Provider){
"data" : {
"id" : "prov-cmEmLstBfjNNA9F3" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "private" ,
"created-at" : "2022-02-11T19:16:59.533Z" ,
"updated-at" : "2022-02-11T19:16:59.533Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "hashicorp" ,
"type" : "organizations"
}
} ,
"versions" : {
"data" : [ ] ,
"links" : {
"related" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
}
{
"data" : {
"id" : "prov-cmEmLstBfjNNA9F3" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "private" ,
"created-at" : "2022-02-11T19:16:59.533Z" ,
"updated-at" : "2022-02-11T19:16:59.533Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "hashicorp" ,
"type" : "organizations"
}
} ,
"versions" : {
"data" : [ ] ,
"links" : {
"related" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
}
» Sample Response (Public Provider){
"data" : {
"id" : "prov-fZn7uHu99ZCpAKZJ" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public" ,
"created-at" : "2020-07-09T19:36:56.288Z" ,
"updated-at" : "2020-07-09T19:36:56.288Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws"
}
}
}
{
"data" : {
"id" : "prov-fZn7uHu99ZCpAKZJ" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public" ,
"created-at" : "2020-07-09T19:36:56.288Z" ,
"updated-at" : "2020-07-09T19:36:56.288Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws"
}
}
}
» Get a ProviderGET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name
» ParametersParameter Description :organization_name
The name of the organization the provider belongs to. :registry_name
Whether this is a publicly maintained provider or private. Must be either public
or private
. :namespace
The namespace of the provider. For private providers this is the same as the :organization_name
parameter. :name
The provider name.
» Sample Request (Private Provider)curl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws
curl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws
» Sample Request (Public Provider)curl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws
curl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws
» Sample Response (Private Provider){
"data" : {
"id" : "prov-cmEmLstBfjNNA9F3" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"created-at" : "2022-02-11T19:16:59.533Z" ,
"updated-at" : "2022-02-11T19:16:59.533Z" ,
"registry-name" : "private" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "hashicorp" ,
"type" : "organizations"
}
} ,
"versions" : {
"data" : [
{
"id" : "provver-y5KZUsSBRLV9zCtL" ,
"type" : "registry-provider-versions"
}
] ,
"links" : {
"related" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
}
{
"data" : {
"id" : "prov-cmEmLstBfjNNA9F3" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"created-at" : "2022-02-11T19:16:59.533Z" ,
"updated-at" : "2022-02-11T19:16:59.533Z" ,
"registry-name" : "private" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "hashicorp" ,
"type" : "organizations"
}
} ,
"versions" : {
"data" : [
{
"id" : "provver-y5KZUsSBRLV9zCtL" ,
"type" : "registry-provider-versions"
}
] ,
"links" : {
"related" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws"
}
}
}
» Sample Response (Public Provider){
"data" : {
"id" : "prov-fZn7uHu99ZCpAKZJ" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public" ,
"created-at" : "2020-07-09T19:36:56.288Z" ,
"updated-at" : "2020-07-09T20:16:20.538Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws"
}
}
}
{
"data" : {
"id" : "prov-fZn7uHu99ZCpAKZJ" ,
"type" : "registry-providers" ,
"attributes" : {
"name" : "aws" ,
"namespace" : "hashicorp" ,
"registry-name" : "public" ,
"created-at" : "2020-07-09T19:36:56.288Z" ,
"updated-at" : "2020-07-09T20:16:20.538Z" ,
"permissions" : {
"can-delete" : true
}
} ,
"relationships" : {
"organization" : {
"data" : {
"id" : "my-organization" ,
"type" : "organizations"
}
}
} ,
"links" : {
"self" : "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws"
}
}
}
» Delete a ProviderDELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name
» ParametersParameter Description :organization_name
The name of the organization to delete a provider from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. :registry_name
Whether this is a publicly maintained provider or private. Must be either public
or private
. :namespace
The namespace of the provider that will be deleted. :name
The name of the provider that will be deleted.
» Sample Request (Private Provider)curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws
» Sample Request (Public Provider)curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws