» Registry Providers API

You can add providers from the public Terraform Registry to your Terraform Cloud private registry. Once added, Terraform Cloud automatically synchronizes public providers with their source on the Terraform Registry.

All members of an organization can view and use public providers and modules, but you need owners team permissions to add them to the private registry.

» Terraform Cloud Registry Implementation

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.

» List public Terraform Registry Providers for an Organization

GET /organizations/:organization_name/registry-providers

Parameter Description
:organization_name The name of the organization to list available providers from.

Lists the providers from the public Terraform Registry that included in the private registry for the specified organization.

Status Response Reason
200 JSON API document (type: "registry-providers") The request was successful
404 JSON API error object Providers 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
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 Request

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

» Create a Provider

POST /organizations/:organization_name/registry-providers

Parameter 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.

» Public providers

When created, the public provider record will be available in the organization's registry provider list. You cannot create versions for public providers; you must use the versions available on the Terraform Registry.

Status Response Reason
201 JSON API document (type: "registry-providers") Successfully published provider
422 JSON API error object Malformed request body (missing attributes, wrong types, etc.)
403 JSON API error object Forbidden - public provider curation disabled
404 JSON API error object User not authorized

» 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 "registry-providers".
data.attributes.name string The name of the provider.
data.attributes.namespace string The namespace of the provider.
data.attributes.registry-name string Must be public.

» Sample Payload (public provider)

{
  "data": {
    "type": "registry-providers",
    "attributes": {
      "name": "aws",
      "namespace": "hashicorp",
      "registry-name": "public"
    }
  }
}

» 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/registry-providers

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

» Get a Provider

GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name

» Parameters

Parameter Description
:organization_name The name of the organization the provider belongs to.
:namespace The namespace of the provider.
:name The provider name.
:registry-name public.
Status Response Reason
200 JSON API document (type: "registry-providers") The request was successful
403 JSON API error object Forbidden - public provider curation disabled
404 JSON API error object Provider not found or user unauthorized to perform action

» 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

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

» Delete a Provider

DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name

» Parameters

Parameter 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.
:namespace The namespace of the provider that will be deleted.
:name The name of the provider that will be deleted.
:registry_name public
Status Response Reason
204 Nothing Success
403 JSON API error object Forbidden - public provider curation disabled
404 JSON API error object Provider not found or user not authorized to perform action

» 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