June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Network Infrastructure
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
    • Run Tasks
    • Run Tasks Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Registry Providers API

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

»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 Terraform Registry Providers for an Organization

GET /organizations/:organization_name/registry-providers

»Parameters

ParameterDescription
:organization_nameThe name of the organization to list available providers from.

Lists the providers included in the private registry for the specified organization.

StatusResponseReason
200JSON API document (type: "registry-providers")Success
404JSON API error objectProviders 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.

ParameterDescription
qOptional. 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
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 Provider

POST /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.

»Parameters

ParameterDescription
:organization_nameThe 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.
StatusResponseReason
201JSON API document (type: "registry-providers")Successfully published provider
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
403JSON API error objectForbidden - public provider curation disabled
404JSON API error objectUser not authorized

»Request Body

Important: 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 pathTypeDefaultDescription
data.typestringMust be "registry-providers".
data.attributes.namestringThe name of the provider.
data.attributes.namespacestringThe namespace of the provider. For private providers this is the same as the :organization_name parameter.
data.attributes.registry-namestringWhether 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 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
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 Provider

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

»Parameters

ParameterDescription
:organization_nameThe name of the organization the provider belongs to.
:registry_nameWhether this is a publicly maintained provider or private. Must be either public or private.
:namespaceThe namespace of the provider. For private providers this is the same as the :organization_name parameter.
:nameThe provider name.
StatusResponseReason
200JSON API document (type: "registry-providers")Success
403JSON API error objectForbidden - public provider curation disabled
404JSON API error objectProvider not found or user unauthorized to perform action

»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 Provider

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

»Parameters

ParameterDescription
:organization_nameThe 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_nameWhether this is a publicly maintained provider or private. Must be either public or private.
:namespaceThe namespace of the provider that will be deleted.
:nameThe name of the provider that will be deleted.
StatusResponseReason
204NothingSuccess
403JSON API error objectForbidden - public provider curation disabled
404JSON API error objectProvider not found or user not authorized to perform action

»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
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager