• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Cloud

Skip to main content
  • Terraform Cloud
  • Plans and Features
  • Getting Started
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Assessment Results
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
    • Projects
    • Project Team Access
    • Runs
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Team Access
    • Workspace Resources
    • Variable Sets
    • Changelog
    • Stability Policy
  • Migrating to Terraform Cloud

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. API
  5. Teams

»Teams API

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.)

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

ParameterDescription
:organization_nameThe name of the organization to list teams from.

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.

ParameterDescription
qOptional. 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 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-run-tasks": true,
          "manage-workspaces": false,
          "manage-vcs-settings": 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

ParameterDescription
:organization_nameThe 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.
StatusResponseReason
200JSON API document (type: "teams")Successfully created a team
400JSON API error objectInvalid include parameter
404JSON API error objectOrganization not found, or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
500JSON API error objectFailure 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 pathTypeDefaultDescription
data.typestringMust be "teams".
data.attributes.namestringThe 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-idstring(nothing)The unique identifier of the team from the SAML MemberOf attribute. Only available in Terraform Enterprise 202204-1 and later, or if the team belongs to an organization in the paid Terraform Cloud Business tier.
data.attributes.organization-accessobject(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-providers, manage-modules, manage-projects, read-projects, and read-workspaces 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).

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 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-run-tasks": false,
        "manage-vcs-settings": false,
        "manage-workspaces": true,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": 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,
      "visibility": "secret"
    },
    "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

ParameterDescription
:team_idThe 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 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-run-tasks": true,
        "manage-workspaces": false,
        "manage-vcs-settings": false,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": false
      }
    },
    "relationships": {
      "users": {
        "data": []
      },
      "authentication-token": {
        "meta": {}
      }
    },
    "links": {
      "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
    }
  }
}

Update a Team

PATCH /teams/:team_id

ParameterDescription
:team_idThe team ID to be updated.
StatusResponseReason
200JSON API document (type: "teams")Successfully created a team
400JSON API error objectInvalid include parameter
404JSON API error objectTeam not found, or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)
500JSON API error objectFailure 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 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 pathTypeDefaultDescription
data.typestringMust be "teams".
data.attributes.namestring(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-idstring(previous value)The unique identifier of the team from the SAML MemberOf attribute. Only available in Terraform Enterprise 202204-1 and later, or if the team belongs to an organization in the paid Terraform Cloud Business tier.
data.attributes.organization-accessobject(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-providers, manage-modules, manage-projects, read-projects, and read-workspaces 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).

Sample Payload

{
  "data": {
    "type": "teams",
    "attributes": {
      "visibility": "organization",
      "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 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-run-tasks": true,
        "manage-vcs-settings": true,
        "manage-workspaces": true,
        "manage-providers": false,
        "manage-modules": false,
        "manage-projects": false,
        "read-projects": false,
        "read-workspaces": true
      },
      "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 a Team

DELETE /teams/:team_id

ParameterDescription
:team_idThe 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

Available Related Resources

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.
Edit this page on GitHub

On this page

  1. Teams API
  2. Organization Membership
  3. List teams
  4. Create a Team
  5. Show Team Information
  6. Update a Team
  7. Delete a Team
  8. Available Related Resources
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)