Teams API
The Teams API is used to create, edit, and destroy teams as well as manage a team's organization-level permissions. TheTeam Membership API is used to add or remove users from a team. Use theTeam Access API to associate a team with privileges on an individual workspace.
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. Seethe 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. |
Query Parameters
This endpoint supports paginationwith 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/teamsSample Response
Thesso-team-id attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform.Theallow-member-token-management attribute is set tofalse 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 | Invalidinclude 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 setmanage-workspaces tofalse when settingmanage-projects totrue, since project permissions cascade down to workspaces. This is also the case forread-workspaces andread-projects. Ifread-projects istrue,read-workspaces must betrue 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 SAMLMemberOf 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 themanage-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, andmanage-organization-access properties with boolean values. All properties default tofalse. |
data.attributes.visibility(beta) | 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/teamsSample Response
Thesso-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-6p5jTwJQXwqZBncCSample Response
Thesso-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 | Invalidinclude 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.
Note: You cannot setmanage-workspaces tofalse when settingmanage-projects totrue, since project permissions cascade down to workspaces. This is also the case forread-workspaces andread-projects. Ifread-projects istrue,read-workspaces must betrue as well.
| 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 SAMLMemberOf 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 themanage-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, andmanage-organization-access properties with boolean values. All properties default tofalse. |
data.attributes.visibility(beta) | 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-6p5jTwJQXwqZBncCSample Response
Thesso-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-6p5jTwJQXwqZBncCAvailable Related Resources
The GET endpoints above can optionally return related resources, if requested withtheinclude 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.