8000 [Do not merge] Member Roles API documentation (#913) · hashicorp/web-unified-docs@4dea505 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4dea505

Browse files
netramalinetramali
authored
[Do not merge] Member Roles API documentation (#913)
1 parent bb7216b commit 4dea505

File tree

9 files changed

+319
-6
lines changed

9 files changed

+319
-6
lines changed

‎content/terraform-docs-common/data/cloud-docs-nav-data.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
{
3737
"title": "Manage access and organizations",
3838
"routes": [
39-
{ "title": "Users", "path": "users-teams-organizations/users" },
39+
{ "title": "Users", "path": "users-teams-organizations/users" },
4040
{
4141
"title": "Teams",
4242
"routes": [
@@ -838,6 +838,7 @@
838838
]
839839
},
840840
{ "title": "Team membership", "path": "api-docs/team-members" },
841+
{ "title": "Group member roles", "path": "api-docs/group-member-roles" },
841842
{ "title": "Team tokens", "path": "api-docs/team-tokens" },
842843
{ "title": "Teams", "path": "api-docs/teams" },
843844
{ "title": "User tokens", "path": "api-docs/user-tokens" },

‎content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,21 @@ description: >-
99

1010
Keep track of changes to the API for HCP Terraform and Terraform Enterprise.
1111

12+
<!-- BEGIN: TFC:only name:hcp-eu -->
13+
14+
## 2025-9-30
15+
* Add a new page for [group member roles](/terraform/cloud-docs/api-docs/group-member-roles) APIs for retrieving information about group permissions for HCP EU organizations. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
16+
* In HashiCorp Cloud Platform (HCP) Europe organizations, you manage user access through HCP groups. HCP Terraform inherits groups and roles from HCP. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
17+
- The following API endpoints are supported by HCP Europe organizations if you use group attributes instead of team attributes:
18+
- [`project-team-access`](/terraform/cloud-docs/api-docs/project-team-access)
19+
- [`team-tokens`](/terraform/cloud-docs/api-docs/team-tokens)
20+
- [`team-access`](/terraform/cloud-docs/api-docs/team-access)
21+
- The following API endpoints are **not** supported by HCP Europe organizations:
22+
- [`team-members`](/terraform/cloud-docs/api-docs/team-members)
23+
- [`teams`](/terraform/cloud-docs/api-docs/teams)
24+
25+
<!-- END: TFC:only name:hcp-eu -->
26+
1227
## 2025-07-11
1328
* Update existing [workspaces API documentation](/terraform/cloud-docs/api-docs/workspaces) to reflect that a workspace's default execution mode now matches the project and not the organization default.
1429
* Update existing [projects API documentation](/terraform/cloud-docs/api-docs/projects) to include `default-execution-mode`, `default-agent-pool`, and `settings-overwrites` for projects.

‎content/terraform-docs-common/docs/cloud-docs/api-docs/group-member-roles.mdx‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
page_title: /member-roles API reference for HCP Terraform
3+
description: >-
4+
Use the HCP Terraform API's group `/member-roles` endpoint to review group permissions for resources.
5+
tfc_only: true
6+
---
7+
8+
[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
9+
10+
[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
11+
12+
[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202
13+
14+
[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204
15+
16+
[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
17+
18+
[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
19+
20+
[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
21+
22+
[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
23+
24+
[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
25+
26+
[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412
27+
28+
[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
29+
30+
[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429
31+
32+
[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
33+
34+
[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504
35+
36+
[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents
37+
38+
[JSON API error object]: https://jsonapi.org/format/#error-objects
39+
40+
# Group member role API reference
41+
42+
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.
43+
44+
<Note>
45+
46+
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](/hcp/docs/hcp/europe).
47+
48+
For other HCP Terraform organizations, refer to the [Team members](/terraform/cloud-docs/api-docs/team-members) API.
49+
50+
</Note>
51+
52+
## List all role assignments
53+
54+
`GET /member-roles/:resource_type/:resource_id`
55+
56+
| Parameter | Description |
57+
| -------------------- | ------------------------------------------------ |
58+
| `:resource_type` | The type of the resource. This can be organizations, projects, workspaces. |
59+
| `:resource_id` | The id of the respective resource. |
60+
61+
62+
### Query Parameters
63+
64+
This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
65+
66+
| Parameter | Description |
67+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68+
| `q` | **Optional.** Allows querying a list of role assignments by group name. This search is case-insensitive. |
69+
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. EA0E |
70+
| `page[size]` | **Optional.** If omitted, the endpoint will return 20 role assignments per page. |
71+
| `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"`). |
72+
73+
### Sample Request
74+
75+
```shell
76+
$ curl \
77+
--header "Authorization: Bearer $TOKEN" \
78+
--header "Content-Type: application/vnd.api+json" \
79+
--request GET \
80+
https://app.terraform.io/api/v2/member-roles/organizations/5574ca0a-4d0b-4456-b1a6-54e8ae4c1b2a?page[number]=1&page[size]=10&sort=
81+
```
82+
83+
### Sample Response
84+
85+
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.
86+
87+
```json
88+
{
89+
"data": [
90+
{
91+
"id": "726a300c45-groups-bbe82f8dcb41025f18c951",
92+
"type": "member-roles",
93+
"attributes": {
94+
"roles": [],
95+
"member-id": "iam.group:hFkn8zpNB6cRp8jnqPkH",
96+
"member-name": "group_D",
97+
"member-type": "groups"
98+
}
99+
},
100+
{
101+
"id": "bee3018293f35b435662b8882e3fc024",
102+
"type": "member-roles",
103+
"attributes": {
104+
"roles": [
105+
{
106+
"resource-type": "organizations",
107+
"role-id": "roles/terraform.legacy-organization-access-custom"
108+
},
109+
{
110+
"resource-type": "organizations",
111+
"role-id": "roles/admin"
112+
}
113+
],
114+
"member-id": "iam.group:HTwTGdftfghn9HHwKJ9w",
115+
"member-name": "group_C",
116+
"member-type": "groups"
117+
}
118+
},
119+
{
120+
"id": "36ed391b9b65ad434576787d46c01af8b8",
121+
"type": "member-roles",
122+
"attributes": {
123+
"roles": [],
124+
"member-id": "iam.group:cTJfbKCJTThcq8pPQJTj",
125+
"member-name": "group_B",
126+
"member-type": "groups"
127+
}
128+
}
129+
],
130+
"links": {
131+
"self": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?page%5Bnumber%5D=1&page%5Bsize%5D=20",
132+
"first": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?page%5Bnumber%5D=1&page%5Bsize%5D=20",
133+
"prev": null,
134+
"next": null,
135+
"last": "https://app.terraform.io/api/v2/member-roles/organizations/4741ca0a-4d0b-4177-b1a6-54e8ae4c1b2a?page%5Bnumber%5D=1&page%5Bsize%5D=20"
136+
},
137+
"meta": {
138+
"pagination": {
139+
"current-page": 1,
140+
"page-size": 20,
141+
"prev-page": null,
142+
"next-page": null,
143+
"total-pages": 1,
144+
"total-count": 19
145+
}
146+
}
147+
}
148+
```
149+
150+
## Show roles for a group
151+
152+
`GET /member-roles/:resource_type/:resource_id`
153+
154+
This endpoint fetches the HCP roles and relevant permissions for a single group on the specified resource.
155+
156+
| Parameter | Description |
157+
| -------------------- | ------------------------------------------------ |
158+
| `:resource_type` | The resource level to view the roles for. This can be organizations, projects, workspaces. |
159+
| `:resource_id` | The id of the resource that is of the type resource_type. |
160+
| `filter[member_type]` | **Required.** Specifies the type of the member. As of now, the only acceptable value is groups. |
161+
| `filter[group_id]` | **Required.** The id of the group that you want to see the permissions for. |
162+
163+
164+
### Query Parameters
165+
166+
This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
167+
168+
| Parameter | Description |
169+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170+
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
171+
| `page[size]` | **Optional.** If omitted, the endpoint will return 10 teams per page. |
172+
173+
### Sample Request
174+
175+
```shell
176+
$ curl \
177+
--header "Authorization: Bearer $TOKEN" \
178+
--header "Content-Type: application/vnd.api+json" \
179+
--request GET \
180+
https://app.terraform.io/api/v2/member-roles/organizations/5574ca0a-4d0b-4456-b1a6-54e8ae4c1b2a?filter[member_type]=groups&filter[member_id]=iam.group%6ANzJbGbHIigBctKmRrTkz
181+
```
182+
183+
### Sample Response
184+
185+
The response shows the hcp and terraform roles for a single member (e.g. group) on the specified resource.
186+
187+
```json
188+
{
189+
"data": [
190+
{
191+
"id": "865a1f57998956c67ae86e745ea61654",
192+
"type": "member-roles",
193+
"attributes": {
194+
"roles": [
195+
{
196+
"resource-type": "organizations",
197+
"role-id": "roles/admin"
198+
},
199+
{
200+
"resource-type": "projects",
201+
"role-id": "roles/terraform.legacy-project-access-custom"
202+
}
203+
],
204+
"member-id": "iam.group:NzJbGbYyLgBctKmDmTkz",
205+
"member-name": "group_A",
206+
"member-type": "groups"
207+
}
208+
}
209+
],
210+
"links": {
211+
"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",
212+
"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",
213+
"prev": null,
214+
"next": null,
215+
"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"
216+
},
217+
"meta": {
218+
"pagination": {
219+
"current-page": 1,
220+
"page-size": 20,
221+
"prev-page": null,
222+
"next-page": null,
223+
"total-pages": 1,
224+
"total-count": 1
225+
}
226+
}
227+
}
228+
```

‎content/terraform-docs-common/docs/cloud-docs/api-docs/index.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ The following entitlements are available:
119119
- `configuration-designer` — Allows an organization to use the [Configuration Designer][].
120120
- `cost-estimation` — Allows an organization to access [cost estimation][].
121121
- `global-run-tasks` — Allows an organization to apply [run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) to every workspace. Affects the [run tasks][] endpoints. This feature is currently in beta.
122+
<!-- BEGIN: TFC:only name:hcp-eu -->
123+
- `groups` - Allows an organization to manage access to its workspaces with [groups](https://docs.hashicorp.com/hcp/docs/hcp/iam/groups) for a HCP Europe organization. To learn more about HCP Europe, refer to the [HCP Europe documentation](/hcp/docs/hcp/europe).
124+
<!-- END: TFC:only name:hcp-eu -->
122125
- `module-tests-generation` - Allows an organization to generate tests for private registry modules. This feature is currently in beta.
123126
- `module-deprecations` - Allows an organization to mark a module version from the Private Registry as deprecated.
124127
- `module-revocations` - Allows an organization to mark a deprecated module version from the Private Registry as revoked.
@@ -160,6 +163,8 @@ The following entitlements are available:
160163

161164
[o-tokens]: /terraform/cloud-docs/api-docs/oauth-tokens
162165

166+
[member roles]: /terraform/cloud-docs/api-docs/member-roles
167+
163168
[plans]: /terraform/cloud-docs/api-docs/plans
164169

165170
[policies]: /terraform/cloud-docs/api-docs/policies

‎content/terraform-docs-common/docs/cloud-docs/api-docs/project-team-access.mdx‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ description: >-
4444

4545
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.
4646

47+
<!-- BEGIN: TFC:only name:hcp-eu -->
48+
49+
<Note>
50+
51+
In HCP Europe organizations, you use HCP **groups** to manage permissions instead of **teams**. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
52+
53+
You can replace team attributes with HCP group attributes in the following `team-project` API endpoints. Each API response can return information about groups and their permissions on projects.
54+
55+
</Note>
56+
57+
<!-- END: TFC:only name:hcp-eu -->
58+
4759
## Resource permissions
4860

4961
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. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage projects** permission enabled has admin access on all projects, even if their `team-project` on a particular project only grants read access. For more information, refer to [Managing Project Access](/terraform/cloud-docs/users-teams-organizations/teams/manage#managing-project-access).
@@ -404,8 +416,8 @@ $ curl \
404416
"attributes": {
405417
"access": "custom",
406418
"project-access": {
407-
"settings": "delete"
408-
"teams": "manage",
419+
"settings": "delete",
420+
"teams": "manage"
409421
},
410422
"workspace-access" : {
411423
"runs": "apply",

‎content/terraform-docs-common/docs/cloud-docs/api-docs/team-access.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ description: >-
4444

4545
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.
4646

47+
<!-- BEGIN: TFC:only name:hcp-eu -->
48+
49+
<Note>
50+
51+
In HCP Europe organizations, you use HCP **groups** to manage permissions instead of **teams**. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
52+
53+
You can replace team attributes with HCP group attributes in the following `team-workspace` API endpoints. Each API response can return information about groups and their permissions on workspaces.
54+
55+
</Note>
56+
57+
<!-- END: TFC:only name:hcp-eu -->
58+
4759
## Resource permissions
4860

4961
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. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage workspaces** permission enabled has admin access on all workspaces, even if their `team-workspace` on a particular workspace only grants read access. For more information, refer to [Managing Workspace Access](/terraform/cloud-docs/users-teams-organizations/teams/manage#managing-workspace-access).

‎content/terraform-docs-common/docs/cloud-docs/api-docs/team-members.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,18 @@ description: >-
4646

4747
The Team Membership API is used to add or remove users from teams. The [Team API](/terraform/cloud-docs/api-docs/teams) is used to create or destroy teams.
4848

49+
<!-- BEGIN: TFC:only name:hcp-eu -->
50+
51+
<Note>
52+
53+
In HCP Europe organizations, you use HCP **groups** to manage permissions instead of **teams**. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
54+
55+
The following team membership APIs are **not** available for HCP Europe organizations. Manage user membership to a group on the [HCP platform](https://portal.cloud.eu.hashicorp.com).
56+
57+
</Note>
58+
59+
<!-- END: TFC:only name:hcp-eu -->
60+
4961
## Organization Membership
5062

5163
-> **Note:** To add users to a team, they must first receive and accept the invitation to join the organization by email. This process ensures that you do not accidentally add the wrong person by mistyping a username. Refer to [the Organization Memberships API documentation](/terraform/cloud-docs/api-docs/organization-memberships) for more information.

‎content/terraform-docs-common/docs/cloud-docs/api-docs/team-tokens.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,18 @@ Teams relying on the [**legacy**](/terraform/cloud-docs/api-docs/team-tokens#leg
4444

4545
You can create and delete team tokens and list an organization's team tokens.
4646

47+
<!-- BEGIN: TFC:only name:hcp-eu -->
48+
49+
<Note>
50+
51+
In HCP Europe organizations, you use HCP **groups** to manage permissions instead of **teams**. To learn more about HCP Europe, refer to [Use HCP Terraform in Europe](/terraform/cloud-docs/europe).
52+
53+
You can replace team attributes with HCP group attributes in the following API endpoints. For example, you can replace `team_id` with `group_id`, and the API responses return group-related information. You can also manage group API tokens on the [HCP platform](https://portal.cloud.eu.hashicorp.com).
54+
55+
</Note>
56+
57+
<!-- END: TFC:only name:hcp-eu -->
58+
4759
## Generate a new team token
4860

4961
Generates a new team token.

0 commit comments

Comments
 (0)
0