page_title |
---|
Teams - API Docs - Terraform Cloud and Terraform Enterprise |
-> Note: Team management is a paid feature, available as part of the Team upgrade package. Single sign-on is also a paid feature, available as part of the Business upgrade package. Refer to Terraform Cloud pricing for details.
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.
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.)
-> 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.
GET organizations/:organization_name/teams
Parameter | Description |
---|---|
:organization_name |
The name of the organization to list teams from. |
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 |
---|---|
page[number] |
Optional. If omitted, the endpoint will return the first page. |
page[size] |
Optional. If omitted, the endpoint will return 20 runs per page. |
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/organizations/my-organization/teams
The sso-team-id
attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
{
"data": [
{
"id": "team-6p5jTwJQXwqZBncC",
"type": "teams",
"attributes": {
"name": "team-creation-test",
"sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
"users-count": 0,
"visibility": "organization",
"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-workspaces": false,
"manage-vcs-settings": false
}
},
"relationships": {
"users": {
"data": []
},
"authentication-token": {
"meta": {}
}
},
"links": {
"self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
}
}
]
}
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 |
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 "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 if the team belongs to an organization in the paid Terraform Cloud Business tier. |
data.attributes.organization-access |
object | (nothing) | Settings for the team's organization access. This object can include manage-policies , manage-policy-overrides , manage-workspaces , manage-vcs-settings , manage-providers , and manage-modules properties with boolean values. All properties default to false . |
data.attributes.visibility (beta) |
string | "secret" |
The team's visibility. Must be "secret" or "organization" (visible). |
{
"data": {
"type": "teams",
"attributes": {
"name": "team-creation-test",
"sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
"organization-access": {
"manage-workspaces": true
}
}
}
}
$ 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
The sso-team-id
attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
{
"data": {
"attributes": {
"name": "team-creation-test",
"sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
"organization-access": {
"manage-policies": false,
"manage-policy-overrides": false,
"manage-vcs-settings": false,
"manage-workspaces": true,
"manage-providers": false,
"manage-modules": 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"
},
"id": "team-6p5jTwJQXwqZBncC",
"links": {
"self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
},
"relationships": {
"authentication-token": {
"meta": {}
},
"users": {
"data": []
}
},
"type": "teams"
}
}
GET /teams/:team_id
Parameter | Description |
---|---|
:team_id |
The team ID to be shown. |
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request GET \
https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC
The sso-team-id
attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
{
"data": {
"id": "team-6p5jTwJQXwqZBncC",
"type": "teams",
"attributes": {
"name": "team-creation-test",
"sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
"users-count": 0,
"visibility": "organization",
"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-workspaces": false,
"manage-vcs-settings": false,
"manage-providers": false,
"manage-modules": false
}
},
"relationships": {
"users": {
"data": []
},
"authentication-token": {
"meta": {}
}
},
"links": {
"self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
}
}
}
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 |
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 if the team belongs to an organization in the paid Terraform Cloud Business tier. |
data.attributes.organization-access |
object | (previous value) | Settings for the team's organization access. This object can include manage-policies , manage-policy-overrides , manage-workspaces , manage-vcs-settings , manage-providers , and manage-modules properties with boolean values. All properties default to false . |
data.attributes.visibility (beta) |
string | (previous value) | The team's visibility. Must be "secret" or "organization" (visible). |
{
"data": {
"type": "teams",
"attributes": {
"visibility": "organization",
"organization-access": {
"manage-vcs-settings": true
}
}
}
}
$ 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
The sso-team-id
attribute is only returned if this team's organization is in the Terraform Cloud Business tier.
{
"data": {
"attributes": {
"name": "team-creation-test",
"sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4",
"organization-access": {
"manage-policies": false,
"manage-policy-overrides": false,
"manage-vcs-settings": true,
"manage-workspaces": true,
"manage-providers": false,
"manage-modules": false
},
"visibility": "organization",
"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 /teams/:team_id
Parameter | Description |
---|---|
:team_id |
The team ID to be deleted. |
$ 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.