» Teams API

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.

» List teams

GET organizations/:organization_name/teams

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

» 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 

{
  "data": [
    {
      "id": "team-6p5jTwJQXwqZBncC",
      "type": "teams",
      "attributes": {
        "name": "team-creation-test",
        "users-count": 0,
        "permissions": {
          "can-update-membership": true,
          "can-destroy": true
        },
        "organization-access": {
          "manage-policies": true,
          "manage-workspaces": false,
          "manage-vcs-settings": 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.

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.organization-access object (nothing) Settings for the team's organization access. This object can include manage-policies, manage-workspaces, and manage-vcs-settings properties with boolean values. All properties default to false.

» Sample Payload 

{
  "data": {
    "type": "teams",
    "attributes": {
      "name": "team-creation-test",
      "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 

{
  "data": {
    "attributes": {
      "name": "team-creation-test",
      "organization-access": {
        "manage-policies": false,
        "manage-vcs-settings": false,
        "manage-workspaces": true
      },
      "permissions": {
        "can-destroy": true,
        "can-update-membership": true
      },
      "users-count": 0
    },
    "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 

{
  "data": {
    "id": "team-6p5jTwJQXwqZBncC",
    "type": "teams",
    "attributes": {
      "name": "team-creation-test",
      "users-count": 0,
      "permissions": {
        "can-update-membership": true,
        "can-destroy": true
      },
      "organization-access": {
        "manage-policies": true,
        "manage-workspaces": false,
        "manage-vcs-settings": false
      }
    },
    "relationships": {
      "users": {
        "data": []
      },
      "authentication-token": {
        "meta": {}
      }
    },
    "links": {
      "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC"
    }
  }
}

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