» Team access API

Note: These API endpoints are in beta and are subject to change.

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

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

» List Team Access to Workspaces

GET /team-workspaces

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

Parameter	Description
`filter[workspace][id]`	Required. The workspace ID to list team access for. Obtain this from the workspace settings or the Show Workspace endpoint.

» Sample Request

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

» Sample Response

{
  "data": [
    {
      "id":"131",
      "type":"team-workspaces",
      "attributes": {
        "access":"read"
      },
      "relationships": {
        "team": {
          "data": {
            "id":"team-BUHBEM97xboT8TVz",
            "type":"teams"
          },
          "links": {
            "related":"/api/v2/teams/devs"
          }
        },
        "workspace": {
          "data": {
            "id":"ws-5vBKrazjYR36gcYX",
            "type":"workspaces"
          },
          "links": {
            "related":"/api/v2/organizations/my-organization/workspaces/ws-5vBKrazjYR36gcYX"
          }
        }
      },
      "links": {
        "self":"/api/v2/team-workspaces/131"
      }
    }
  ]
}

» Add Team Access to a Workspace

POST /team-workspaces

» 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	Description
`data.type`	string	Must be `"team-workspaces"`.
`data.attributes.access`	string	The type of access to grant. Valid values are `read`, `plan`, `write`, or `admin`.
`data.relationships.workspace.data.type`	string	Must be `workspaces`.
`data.relationships.workspace.data.id`	string	The workspace 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 workspace.

» Sample Payload

{
  "data": {
    "attributes": {
      "access":"read"
    },
    "relationships": {
      "workspace": {
        "data": {
          "type":"workspaces",
          "id":"ws-5vBKrazjYR36gcYX"
        }
      },
      "team": {
        "data": {
          "type":"teams",
          "id":"team-BUHBEM97xboT8TVz"
        }
      }
    },
    "type":"team-workspaces"
  }
}

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

» Sample Response

{
  "data": {
    "id":"131",
    "type":"team-workspaces",
    "attributes": {
      "access":"read"
    },
    "relationships": {
      "team": {
        "data": {
          "id":"team-BUHBEM97xboT8TVz",
          "type":"teams"
        },
        "links": {
          "related":"/api/v2/teams/devs"
        }
      },
      "workspace": {
        "data": {
          "id":"ws-5vBKrazjYR36gcYX",
          "type":"workspaces"
        },
        "links": {
          "related":"/api/v2/organizations/my-organization/workspaces/ws-5vBKrazjYR36gcYX"
        }
      }
    },
    "links": {
      "self":"/api/v2/team-workspaces/131"
    }
  }
}

» Show Team Access to a Workspace

GET /team-workspaces/:id`

Parameter	Description
`:id`	The ID of the team/workspace 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-workspaces/257525

» Sample Response

{
  "data": {
    "type": "team-workspaces",
    "id": "1",
    "attributes": { "permission": "read" }
  }
}

» Remove Team Access to a Workspace

DELETE /team-workspaces/:id

Parameter	Description
`:id`	The ID of the team/workspace 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-workspaces/257525