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.)
List Team Access to a Project
GET /team-projects
Status | Response | Reason |
---|---|---|
[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.
Parameter | Description |
---|---|
filter[project][id] | Required. The project ID to list team access for. |
page[number] | Optional. |
page[size] | Optional. |
Sample Request
Sample Response
Show a Team Access relationship
GET /team-projects/:id
Status | Response | Reason |
---|---|---|
[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 |
Parameter | Description |
---|---|
:id | The ID of the team/project relationship. Obtain this from the list team access action described above. |
Sample Request
Sample Response
Add Team Access to a Project
POST /team-projects
Status | Response | Reason |
---|---|---|
[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 path | Type | Default | Description | |
---|---|---|---|---|
data.type | string | Must be "team-projects" . | ||
data.attributes.access | string | The type of access to grant. Valid values are read or admin . | ||
data.relationships.project.data.type | string | Must be projects . | ||
data.relationships.project.data.id | string | The project ID to which the team is to be added. | ||
data.relationships.team.data.type | string | Must be teams . | ||
data.relationships.team.data.id | string | The ID of the team to add to the project. |
Sample Payload
Sample Request
Sample Response
Update Team Access to a Project
PATCH /team-projects/:id
Status | Response | Reason |
---|---|---|
[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.) |
Parameter | Description | ||
---|---|---|---|
:id | The ID of the team/project relationship. Obtain this from the list team access action described above. | ||
data.attributes.access | string | The type of access to grant. Valid values are read or admin . |
Sample Request
Sample Payload
Sample Response
Remove Team Access from a Project
DELETE /team-projects/:id
Status | Response | Reason |
---|---|---|
[204][] | The Team Access was successfully destroyed | |
[404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action |
Parameter | Description |
---|---|
:id | The ID of the team/project relationship. Obtain this from the list team access action described above. |
Sample Request