Group member role API reference

The group member role API returns the assigned roles for an HCP group on a given resource, such as an organization, project, or a workspace.

Note

This API is only available for HCP Europe organizations. If your URL includes portal.cloud.eu.hashicorp or app.eu.terraform.io, then you are in an HCP Europe organization. To learn more about HCP Europe, refer to the HCP Europe documentation.

For other HCP Terraform organizations, refer to the Team members API.

List all role assignments

GET /member-roles/:resource_type/:resource_id

Parameter	Description
`:resource_type`	The type of the resource. This can be organizations, projects, workspaces.
`:resource_id`	The id of the respective resource.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`q`	Optional. Allows querying a list of role assignments by group name. This search is case-insensitive.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 role assignments per page.
`sort`	Optional. Allows sorting by group names. The only valid value is `"name"`. Prepending a hyphen to the sort parameter will reverse the order (e.g. `"-name"`).

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/member-roles/organizations/5574ca0a-4d0b-4456-b1a6-54e8ae4c1b2a?page[number]=1&page[size]=10&sort=

Sample Response

The response shows the ID and name of the HCP groups, as well as the HCP and HCP Terraform permissions that group has access to. The resource-type attribute determines at which resource level, such as organization, project, or workspace, that the role is coming from.

{
  "data": [
    {
      "id": "726a300c45-groups-bbe82f8dcb41025f18c951",
      "type": "member-roles",
      "attributes": {
        "roles": [],
        "member-id": "iam.group:hFkn8zpNB6cRp8jnqPkH",
        "member-name": "group_D",
        "member-type": "groups"
      }
    },
    {
      "id": "bee3018293f35b435662b8882e3fc024",
      "type": "member-roles",
      "attributes": {
        "roles": [
            {
              "resource-type": "organizations",
              "role-id": "roles/terraform.legacy-organization-access-custom"
            },
            {
              "resource-type": "organizations",
              "role-id": "roles/admin"
            }
        ],
        "member-id": "iam.group:HTwTGdftfghn9HHwKJ9w",
        "member-name": "group_C",
        "member-type": "groups"
      }
    },
    {
      "id": "36ed391b9b65ad434576787d46c01af8b8",
      "type": "member-roles",
      "attributes": {
        "roles": [],
        "member-id": "iam.group:cTJfbKCJTThcq8pPQJTj",
        "member-name": "group_B",
        "member-type": "groups"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?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": 19
    }
  }
}

Show roles for a group

GET /member-roles/:resource_type/:resource_id

This endpoint fetches the HCP roles and relevant permissions for a single group on the specified resource.

Parameter	Description
`:resource_type`	The resource level to view the roles for. This can be organizations, projects, workspaces.
`:resource_id`	The id of the resource that is of the type resource_type.
`filter[member_type]`	Required. Specifies the type of the member. As of now, the only acceptable value is groups.
`filter[group_id]`	Required. The id of the group that you want to see the permissions for.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 10 teams per page.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/member-roles/organizations/5574ca0a-4d0b-4456-b1a6-54e8ae4c1b2a?filter[member_type]=groups&filter[member_id]=iam.group%6ANzJbGbHIigBctKmRrTkz

Sample Response

The response shows the hcp and terraform roles for a single member (e.g. group) on the specified resource.

{
  "data": [
    {
      "id": "865a1f57998956c67ae86e745ea61654",
      "type": "member-roles",
      "attributes": {
        "roles": [
          {
            "resource-type": "organizations",
            "role-id": "roles/admin"
          },
          {
            "resource-type": "projects",
            "role-id": "roles/terraform.legacy-project-access-custom"
          }
        ],
        "member-id": "iam.group:NzJbGbYyLgBctKmDmTkz",
        "member-name": "group_A",
        "member-type": "groups"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/member-roles/projects/e78425e5-af7a-40ec-b62c-9a97331b1cd0?filter%5Bmember_id%5D=iam.group%3ANzJbGbHbLgBctKmDmTkz\u0026filter%5Bmember_type%5D=groups\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/member-roles/projects/e78425e5-af7a-40ec-b62c-9a97331b1cd0?filter%5Bmember_id%5D=iam.group%3ANzJbGbHbLgBctKmDmTkz\u0026filter%5Bmember_type%5D=groups\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/member-roles/projects/e78425e5-af7a-40ec-b62c-9a97331b1cd0?filter%5Bmember_id%5D=iam.group%3ANzJbGbHbLgBctKmDmTkz\u0026filter%5Bmember_type%5D=groups\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}