Team membership API reference

Use the team membership API to add or remove users from teams. To create or destroy teams, refer to the teams API documentation.

Team management is available in HCP Terraform Essentials, Standard, and Premium editions. Free organizations can also use this API, but can only manage membership of their owners team. Refer to the Terraform pricing page for more information.

For teams managed by your identity provider (IdP) through SCIM, HCP Terraform rejects calls to update the team membership. Use your identity provider to make changes, which HCP Terraform applies through the SCIM provisioning endpoints.

Refer to SCIM provisioning for more information.

Note

In HCP Europe organizations, you use HCP groups to manage permissions instead of teams. To learn more about HCP Europe, refer to Use HCP Terraform in Europe.

The following team membership APIs are not available for HCP Europe organizations. Manage user membership to a group on the HCP platform.

Organization Membership

Note: To add users to a team, they must first receive and accept the invitation to join the organization by email. This process ensures that you do not accidentally add the wrong person by mistyping a username. Refer to the Organization Memberships API documentation for more information.

Add a User to Team (With user ID)

This method adds multiple users to a team using the user ID. Both users and teams must already exist.

POST /teams/:team_id/relationships/users

Parameter	Description
`:team_id`	The ID of the team.

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 `"users"`.
`data[].id`	string		The ID of the user you want to add to this team.

Sample Payload

{
  "data": [
    {
      "type": "users",
      "id": "myuser1"
    },
    {
      "type": "users",
      "id": "myuser2"
    }
  ]
}

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/teams/257525/relationships/users

Add a User to Team (With organization membership ID)

This method adds multiple users to a team using the organization membership ID. Unlike the user ID method, the user only needs an invitation to the organization.

POST /teams/:team_id/relationships/organization-memberships

Parameter	Description
`:team_id`	The ID of the team.

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 `"organization-memberships"`.
`data[].id`	string		The organization membership ID of the user to add.

Sample Payload

{
  "data": [
    {
      "type": "organization-memberships",
      "id": "ou-nX7inDHhmC3quYgy"
    },
    {
      "type": "organization-memberships",
      "id": "ou-tTJph1AQVK5ZmdND"
    }
  ]
}

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/teams/257525/relationships/organization-memberships

Delete a User from Team (With username)

This method removes multiple users from a team using the username. Both users and teams must already exist. This method only removes a user from this team. It does not delete that user overall.

DELETE /teams/:team_id/relationships/users

Parameter	Description
`:team_id`	The ID of the team.

Request Body

This DELETE 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 `"users"`.
`data[].id`	string		The username of the user to remove from this team.

Sample Payload

{
  "data": [
    {
      "type": "users",
      "id": "myuser1"
    },
    {
      "type": "users",
      "id": "myuser2"
    }
  ]
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/teams/257525/relationships/users

Delete a User from Team (With organization membership ID)

This method removes multiple users from a team using the organization membership ID. This method only removes a user from this team. It does not delete that user overall.

DELETE /teams/:team_id/relationships/organization-memberships

Parameter	Description
`:team_id`	The ID of the team.

Request Body

This DELETE 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 `"organization-memberships"`.
`data[].id`	string		The organization membership ID of the user to remove.

Sample Payload

{
  "data": [
    {
      "type": "organization-memberships",
      "id": "ou-nX7inDHhmC3quYgy"
    },
    {
      "type": "organization-memberships",
      "id": "ou-tTJph1AQVK5ZmdND"
    }
  ]
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/teams/257525/relationships/organization-memberships