HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202307-1. View latest version.

Project Team Access API

Note: Team management is a paid feature, available as part of the Team upgrade package. Learn more about Terraform Cloud pricing here.

The team access APIs are used to associate a team to permissions on a project. A single team-project resource contains the relationship between the Team and Project, including the privileges the team has on the project.

Note: A team-project resource represents a team's local permissions on a specific project. Teams can also have organization-level permissions that grant access to projects, and Terraform Cloud uses whichever access level is higher. (For example: a team with the "manage projects" permission has admin access on all projects, even if their team-project on a particular project only grants read access.) For more information, see Managing Project Access.

Any member of an organization can view team access relative to their own team memberships, including secret teams of which they are a member. Organization owners and project admins can modify team access or view the full set of secret team accesses. The organization token and the owners team token can act as an owner on these endpoints. (More about permissions.)

Project Team Access Levels

Access LevelDescription
readRead project and Read workspace access role on project workspaces
writeRead project and Write workspace access role on project workspaces
maintainRead project and Admin workspace access role on project workspaces
adminAdmin project, Admin workspace access role on project workspaces, create workspaces within project, move workspaces between projects, manage project team access

List Team Access to a Project

GET /team-projects

StatusResponseReason
[200][][JSON API document][] (type: "team-projects")The request was successful
[404][][JSON API error object][]Project not found or user unauthorized to perform action

Query Parameters

These are standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

This endpoint supports pagination with standard URL query parameters.

ParameterDescription
filter[project][id]Required. The project ID to list team access for.
page[number]Optional.
page[size]Optional.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi"

Sample Response

{
  "data": [
    {
      "id": "tprj-TLznAnYdcsD2Dcmm",
      "type": "team-projects",
      "attributes": {
        "access": "read"
      },
      "relationships": {
        "team": {
          "data": {
            "id": "team-KpibQGL5GqRAWBwT",
            "type": "teams"
          },
          "links": {
            "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT"
          }
        },
        "project": {
          "data": {
            "id": "prj-ckZoJwdERaWcFHwi",
            "type": "projects"
          },
          "links": {
            "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi"
          }
        }
      },
      "links": {
        "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a Team Access relationship

GET /team-projects/:id

StatusResponseReason
[200][][JSON API document][] (type: "team-projects")The request was successful
[404][][JSON API error object][]Team access not found or user unauthorized to perform action
ParameterDescription
:idThe ID of the team/project relationship. Obtain this from the list team access action described above.

Sample Request

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

Sample Response

{
  "data": {
    "id": "tprj-TLznAnYdcsD2Dcmm",
    "type": "team-projects",
    "attributes": {
      "access": "read"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-KpibQGL5GqRAWBwT",
          "type": "teams"
        },
        "links": {
          "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT"
        }
      },
      "project": {
        "data": {
          "id": "prj-ckZoJwdERaWcFHwi",
          "type": "projects"
        },
        "links": {
          "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi"
        }
      }
    },
    "links": {
      "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm"
    }
  }
}

Add Team Access to a Project

POST /team-projects

StatusResponseReason
[200][][JSON API document][] (type: "team-projects")The request was successful
[404][][JSON API error object][]Project or Team not found or user unauthorized to perform action
[422][][JSON API error object][]Malformed request body (missing attributes, wrong types, etc.)

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 pathTypeDefaultDescription
data.typestringMust be "team-projects".
data.attributes.accessstringThe type of access to grant. Valid values are read, write, maintain, admin.
data.relationships.project.data.typestringMust be projects.
data.relationships.project.data.idstringThe project ID to which the team is to be added.
data.relationships.team.data.typestringMust be teams.
data.relationships.team.data.idstringThe ID of the team to add to the project.

Sample Payload

{
  "data": {
    "attributes": {
      "access": "read"
    },
    "relationships": {
      "project": {
        "data": {
          "type": "projects",
          "id": "prj-ckZoJwdERaWcFHwi"
        }
      },
      "team": {
        "data": {
          "type": "teams",
          "id": "team-xMGyoUhKmTkTzmAy"
        }
      }
    },
    "type": "team-projects"
  }
}

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/team-projects

Sample Response

{
  "data": {
    "id": "tprj-WbG7p5KnT7S7HZqw",
    "type": "team-projects",
    "attributes": {
      "access": "read"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-xMGyoUhKmTkTzmAy",
          "type": "teams"
        },
        "links": {
          "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy"
        }
      },
      "project": {
        "data": {
          "id": "prj-ckZoJwdERaWcFHwi",
          "type": "projects"
        },
        "links": {
          "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi"
        }
      }
    },
    "links": {
      "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw"
    }
  }
}

Update Team Access to a Project

PATCH /team-projects/:id

StatusResponseReason
[200][][JSON API document][] (type: "team-projects")The request was successful
[404][][JSON API error object][]Team Access not found or user unauthorized to perform action
[422][][JSON API error object][]Malformed request body (missing attributes, wrong types, etc.)
ParameterDescription
:idThe ID of the team/project relationship. Obtain this from the list team access action described above.
data.attributes.accessstringThe type of access to grant. Valid values are read, write, maintain, admin.

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/team-projects/tprj-WbG7p5KnT7S7HZqw

Sample Payload

{
  "data": {
    "id": "tprj-WbG7p5KnT7S7HZqw",
    "attributes": {
      "access": "admin"
    }
  }
}

Sample Response

{
  "data": {
    "id": "tprj-WbG7p5KnT7S7HZqw",
    "type": "team-projects",
    "attributes": {
      "access": "admin"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-xMGyoUhKmTkTzmAy",
          "type": "teams"
        },
        "links": {
          "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy"
        }
      },
      "project": {
        "data": {
          "id": "prj-ckZoJwdERaWcFHwi",
          "type": "projects"
        },
        "links": {
          "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi"
        }
      }
    },
    "links": {
      "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw"
    }
  }
}

Remove Team Access from a Project

DELETE /team-projects/:id

StatusResponseReason
[204][]The Team Access was successfully destroyed
[404][][JSON API error object][]Team Access not found or user unauthorized to perform action
ParameterDescription
:idThe ID of the team/project relationship. Obtain this from the list team access action described above.

Sample Request

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