Bitbucket Integration Fails in Terraform Enterprise with Unauthorized Error – HashiCorp Help Center

Problem

When you attempt to link a Bitbucket repository as a VCS provider in Terraform Enterprise, the operation fails and the application logs show an authorization error.

The following error message appears in the logs, indicating a permissions issue.

{
  "level": "ERROR",
  "trace_id": "b9836c40-0953-4216-a3ca-d9618acd8a03",
  "response_class": "Net::HTTPUnauthorized",
  "url": "https://bitbucket.example.com/rest/api/1.0/projects/PROJECT/repos/REPO/webhooks",
  "request_headers": {
    "Accept": "application/json"
  },
  "response": {
    "errors": [
      {
        "context": null,
        "message": "You are not permitted to access this resource",
        "exceptionName": "com.atlassian.bitbucket.AuthorisationException"
      }
    ]
  }
}

Cause

Terraform Enterprise integrates with Bitbucket by creating webhooks on repositories to trigger automated runs. This error occurs because the Bitbucket user or OAuth consumer configured in Terraform Enterprise lacks the necessary permissions to create and manage these webhooks.

Key indicators from the log confirm this issue:

Error Class: Net::HTTPUnauthorized
Exception Name: com.atlassian.bitbucket.AuthorisationException
Message: You are not permitted to access this resource

Solutions

Here are several solutions to resolve the permissions issue.

Solution 1: Grant Correct Permissions in Bitbucket

Ensure the Bitbucket user or OAuth consumer that Terraform Enterprise uses has the following permissions on the target repository:

Repositories: Admin
Pull Requests: Write
Webhooks: Read and Write

These permissions are required for Terraform Enterprise to automatically create and manage the webhooks necessary for triggering runs.

Solution 2: Verify OAuth Consumer Configuration

Review the OAuth consumer settings in Bitbucket to ensure they are correctly configured for your Terraform Enterprise instance.

Confirm the OAuth consumer or service account is active.
Ensure the callback URL in Bitbucket matches the Terraform Enterprise hostname.
Verify that the RSA public key in Bitbucket matches the private key configured in Terraform Enterprise.

Solution 3: Test Network Connectivity

From the Terraform Enterprise host, verify that you can connect to the Bitbucket API without an authorization failure. Run the following command.

$ curl -vL -o /dev/null https://<bitbucket-host>/rest/api/1.0/projects

A 401 Unauthorized response indicates that the credentials or permissions are still incorrect and need to be re-evaluated.

Solution 4: Use Narrower Permissions

If your organization's security policies prevent granting full repository admin permissions, you can use a more restrictive set of permissions. At a minimum, the account must have:

Webhook management rights (create, read, delete).
Pull request write access to allow run triggers.

Outcome

After you apply the correct permissions, Terraform Enterprise should successfully link the Bitbucket repository, automatically create the required webhook, and trigger runs in response to code changes in the repository.

Additional Information

For more details on configuring this integration, refer to the official documentation on Bitbucket Cloud VCS Integration.