Teams API reference

The Teams API is used to create, edit, and destroy teams as well as manage a team's organization-level permissions. The Team Membership API is used to add or remove users from a team. Use the Team Access API to associate a team with privileges on an individual workspace.

Note: Team management is available in HCP Terraform Standard, Plus, and Premium editions. Refer to HCP Terraform pricing for details.

Any member of an organization can view visible teams and any secret teams they are a member of. Only organization owners can modify teams or view the full set of secret teams. The organization token and the owners team token can act as an owner on these endpoints. (More about permissions.)

Organization Membership

Note: Users must be invited to join organizations before they can be added to teams. See the Organization Memberships API documentation for more information. Invited users who have not yet accepted will not appear in Teams API responses.

List teams

GET organizations/:organization_name/teams

Parameter	Description
`:organization_name`	The name of the organization to list teams from.

The response may identify HashiCorp API service accounts, for example api-team_XXXXXX, as a members of a team. However, API service accounts do not appear in the UI. As a result, there may be differences between the number of team members reported by the UI and the API. For example, the UI may report 0 members on a team when and the API reports 1.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`q`	Optional. Allows querying a list of teams by name. This search is case-insensitive.
`filter[names]`	Optional. If specified, restricts results to a team with a matching name. If multiple comma separated values are specified, teams matching any of the names are returned.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 teams per page.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/my-organization/teams

Sample Response

The sso-team-id attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. The allow-member-token-management attribute is set to false for Terraform Enterprise versions older than 202408-1.

{
  "data": [
    {
      "id": "team-6p5jTwJQXwqZBncC",
      "type": "teams",
      "attributes": {
        "name": "team-creation-test",
        "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
        "users-count": 0,
        "visibility": "organization",
        "allow-member-token-management": true,
        "permissions": {
          "can-update-membership": true,
          "can-destroy": true,
          "can-update-organization-access": true,
          "can-update-api-token": true,
          "can-update-visibility": true
        },
        "organization-access": {
          "manage-policies": true,
          "manage-policy-overrides": false,
          "manage-run-tasks": true,
          "manage-workspaces": false,
          "manage-vcs-settings": false,
          "manage-agent-pools": false,
          "manage-projects": false,
          "read-projects": false,
          "read-workspaces": false
        }
      },
      "relationships": {
        "users": {
          "data": []
        },
        "authentication-token": {
          "meta": {}
        }
      },
      "links": {
        "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
      }
    }
  ]
}

Create a Team

POST /organizations/:organization_name/teams

Parameter	Description
`:organization_name`	The name of the organization to create the team in. The organization must already exist in the system, and the user must have permissions to create new teams.

Status	Response	Reason
200	JSON API document (`type: "teams"`)	Successfully created a team
400	JSON API error object	Invalid `include` parameter
404	JSON API error object	Organization not found, or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)
500	JSON API error object	Failure during team creation

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Note: You cannot set manage-workspaces to false when setting manage-projects to true, since project permissions cascade down to workspaces. This is also the case for read-workspaces and read-projects. If read-projects is true, read-workspaces must be true as well.

Key path	Type	Default	Description
`data.type`	string		Must be `"teams"`.
`data.attributes.name`	string		The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization.
`data.attributes.sso-team-id`	string	(nothing)	The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform.
`data.attributes.organization-access`	object	(nothing)	Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`.
`data.attributes.visibility`	string	`"secret"`	The team's visibility. Must be `"secret"` or `"organization"` (visible).

Sample Payload

{
  "data": {
    "type": "teams",
    "attributes": {
      "name": "team-creation-test",
      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
      "organization-access": {
        "manage-workspaces": true
      }
    }
  }
}

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/organizations/my-organization/teams

Sample Response

The sso-team-id attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform.

{
  "data": {
    "attributes": {
      "name": "team-creation-test",
      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
      "organization-access": {
        "manage-policies": false,
        "manage-policy-overrides": false,
        "manage-run-tasks": false,
        "manage-vcs-settings": false,
        "manage-agent-pools": false,
        "manage-workspaces": true,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": true,
        "manage-membership": false,
        "manage-teams": false,
        "manage-organization-access": false
      },
      "permissions": {
        "can-update-membership": true,
        "can-destroy": true,
        "can-update-organization-access": true,
        "can-update-api-token": true,
        "can-update-visibility": true
      },
      "users-count": 0,
      "visibility": "secret",
      "allow-member-token-management": true
    },
    "id": "team-6p5jTwJQXwqZBncC",
    "links": {
      "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
    },
    "relationships": {
      "authentication-token": {
        "meta": {}
      },
      "users": {
        "data": []
      }
    },
    "type": "teams"
  }
}

Show Team Information

GET /teams/:team_id

Parameter	Description
`:team_id`	The team ID to be shown.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC

Sample Response

The sso-team-id attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform.

{
  "data": {
    "id": "team-6p5jTwJQXwqZBncC",
    "type": "teams",
    "attributes": {
      "name": "team-creation-test",
      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
      "users-count": 0,
      "visibility": "organization",
      "allow-member-token-management": true,
      "permissions": {
        "can-update-membership": true,
        "can-destroy": true,
        "can-update-organization-access": true,
        "can-update-api-token": true,
        "can-update-visibility": true
      },
      "organization-access": {
        "manage-policies": true,
        "manage-policy-overrides": false,
        "manage-run-tasks": true,
        "manage-workspaces": false,
        "manage-vcs-settings": false,
        "manage-agent-pools": false,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": false,
        "manage-membership": false,
        "manage-teams": false,
        "manage-organization-access": false
      }
    },
    "relationships": {
      "users": {
        "data": []
      },
      "authentication-token": {
        "meta": {}
      }
    },
    "links": {
      "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
    }
  }
}

Update a Team

PATCH /teams/:team_id

Parameter	Description
`:team_id`	The team ID to be updated.

Status	Response	Reason
200	JSON API document (`type: "teams"`)	Successfully created a team
400	JSON API error object	Invalid `include` parameter
404	JSON API error object	Team not found, or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)
500	JSON API error object	Failure during team creation

Request Body

This PATCH 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 `"teams"`.
`data.attributes.name`	string	(previous value)	The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization.
`data.attributes.sso-team-id`	string	(previous value)	The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform.
`data.attributes.organization-access`	object	(previous value)	Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`.
`data.attributes.visibility`	string	(previous value)	The team's visibility. Must be `"secret"` or `"organization"` (visible).
`data.attributes.allow-team-token-management`	boolean	(previous value)	The ability to enable and disable team token management for a team. Defaults to true.

Sample Payload

{
  "data": {
    "type": "teams",
    "attributes": {
      "visibility": "organization",
      "allow-member-token-management": true,
      "organization-access": {
        "manage-vcs-settings": true
      }
    }
  }
}

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC

Sample Response

The sso-team-id attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform.

{
  "data": {
    "attributes": {
      "name": "team-creation-test",
      "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
      "organization-access": {
        "manage-policies": false,
        "manage-policy-overrides": false,
        "manage-run-tasks": true,
        "manage-vcs-settings": true,
        "manage-agent-pools": false,
        "manage-workspaces": true,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": true,
        "manage-membership": false,
        "manage-teams": false,
        "manage-organization-access": false
      },
      "visibility": "organization",
      "allow-member-token-management": true,
      "permissions": {
        "can-update-membership": true,
        "can-destroy": true,
        "can-update-organization-access": true,
        "can-update-api-token": true,
        "can-update-visibility": true
      },
      "users-count": 0
    },
    "id": "team-6p5jTwJQXwqZBncC",
    "links": {
      "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
    },
    "relationships": {
      "authentication-token": {
        "meta": {}
      },
      "users": {
        "data": []
      }
    },
    "type": "teams"
  }
}

Delete a Team

DELETE /teams/:team_id

Parameter	Description
`:team_id`	The team ID to be deleted.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

users (string) - Returns the full user record for every member of a team.
organization-memberships (string) - Returns the full organization membership record for every member of a team.

Teams API reference

Organization Membership

List teams

Query Parameters

Sample Request

Sample Response

Create a Team

Request Body

Sample Payload

Sample Request

Sample Response

Show Team Information

Sample Request

Sample Response

Update a Team

Request Body

Sample Payload

Sample Request

Sample Response

Delete a Team

Sample Request

Available Related Resources