Error When Adding a User to a Team in Terraform Enterprise API: "user-xyz does not exist"

Problem

When you attempt to add a user to a team in Terraform Enterprise using the official API endpoint, you may encounter the following 400 Bad Request error.

{
  "errors": [
    {
      "status": "400",
      "title": "bad request",
      "detail": "user-xyz does not exist"
    }
  ]
}

Prerequisites

• You have admin or team management access in Terraform Enterprise.
• You have the correct team ID for the team where you want to add the user.
• The user already exists in the Terraform Enterprise organization.
• You have an API authentication token with sufficient permissions.

Cause

The API documentation includes the following key path information for the request payload.

While the documentation's description states that the id field should be the user's system-generated ID, the API endpoint expects the username (for example, john). Providing the user's system-generated ID causes the API to return the "user-xyz does not exist" error.

Solution

To resolve this issue, you must provide the user's username instead of their user ID in the id field of the JSON payload.

An example of a correct request payload is shown below.

{
  "data": [
    {
      "type": "users",
      "id": "john"
    }
  ]
}

Outcome

After you update the payload to use the username instead of the user ID, the API request will succeed, and Terraform Enterprise will add the user to the specified team.

Additional Information

For more details, please refer to the official Team Members API documentation.