Team membership API reference

The Team Membership API is used to add or remove users from teams. The Team API is used to create or destroy teams.

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 user ID)

This method removes multiple users from a team using the user ID. 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 ID 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