Skip to content

Latest commit

 

History

History
338 lines (286 loc) · 12.4 KB

project-team-access.mdx

File metadata and controls

338 lines (286 loc) · 12.4 KB

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. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

Parameter Description
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"
      }
    }
  ]
}

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

$ 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

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

{
  "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

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

$ 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

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

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