Adding a Team to HCP Terraform Workspace via API fails with 404 when using a Team Token

Avatar
Dimpy Chugh
  • Updated

 

Introduction

When using the HCP Terraform API to add a team to a workspace (POST /api/v2/team-workspaces), you may encounter a 404 not found error. This behaviour depends on the type of API token used, as well as the permissions and visibility settings of the team being added.

Adding Team Access to a Workspace API request returns:

{
  "errors": [{
    "status": "404",
    "title": "not found"
  }]
}

This can occur even when:

  • The workspace ID and team ID are confirmed to exist

  • The same request succeeds when using some tokens but fails with others

 

This article explains:

  • Why different token types behave differently

  • Required permissions for personal and team tokens

  • How to successfully add teams to workspaces using the API

 

Cause

The 404 not found response is expected behaviour when:

  • The API token lacks sufficient organization-level permissions, or

  • The target team is not visible to the caller

HCP Terraform intentionally returns a 404 instead of a 403 to prevent disclosure of information about teams or workspaces the caller is not authorised to access.

 

Solutions

Token Behaviour and Requirements

Case 1: Personal Token (User is a Member of the Target Team)

Result: Request succeeds

Reason:
Any member of an organization can view team access related to their own team memberships, including secret teams they are a part of.

Case 2: Personal Token (User is NOT a Member of the Target Team)

Result: 404 not found

Reason:
To add a team you are not a member of, your user must have organization-level workspace admin permissions.

Requirement:

  • Belong to a team with Manage all workspaces permission
    OR

  • Be part of the Owners team
    OR

  • Use an Organization token

Case 3: Team Token for the Same Team Being Added

Result: 404 not found

Reason:
A team token cannot add itself to a workspace unless it has sufficient organization-level permissions.

Required Configuration:

  1. Go to Organization Settings → Teams

  2. Select the team

  3. Under Organization Access → Workspace Permissions

  4. Enable Manage all workspaces

  5. Save changes

After this, the team token can successfully associate the team with workspaces.

Case 4: Using A Team Token to Add a Different Team to a Workspace

Result: A different team token can be used to add another team to a workspace, provided the following conditions are met:

Requirements:

  1. The token-owning team must have Manage all workspaces permission

  2. The team being added must have Visible team visibility at the organization level

  •  How to Enable Team Visibility:

    • Navigate to Settings → Teams

    • Select the team

    • Set visibility to Visible 

      Note : Visible teams can be seen by all users in the organization, and non-members have read-only access.

 

Key Resolution
Teams with Secret visibility cannot be managed by other teams unless the caller has owner-level privileges.

 

Outcome 

After updating the team visibility to Visible, the API request succeeds and teams can be added to any workspace as expected.

 

Additional Information

Articles in this section

See more