-
Notifications
You must be signed in to change notification settings - Fork 79
[Do not merge] Member Roles API documentation #913
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
8280380
doc changes for member roles
netramali 1b9eb2e
changelog comments addressed
netramali 5b46d29
comments addressed
netramali 320436e
comments addressed
netramali 3654f44
comments addressed
netramali 11437ee
comments addressed
netramali cce0cc4
comments addressed
netramali 926fa6a
Fixed the error with the unhappy notes
rkoron007 5fd31a0
Merge branch 'main' into netramali/member-roles-api-doc
rkoron007 5cbf1d8
Ooops git conflict
rkoron007 66cc420
Fix spacing
rkoron007 a01ad59
Align format and language
rkoron007 a157f4b
Merge branch 'main' into netramali/member-roles-api-doc
rkoron007 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
228 changes: 228 additions & 0 deletions
228
content/terraform-docs-common/docs/cloud-docs/api-docs/group-member-roles.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,228 @@ | ||
| --- | ||
| page_title: /member-roles API reference for HCP Terraform | ||
| description: >- | ||
| Use the HCP Terraform API's group `/member-roles` endpoint to review group permissions for resources. | ||
| tfc_only: true | ||
| --- | ||
|
|
||
| [200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 | ||
|
|
||
| [201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 | ||
|
|
||
| [202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 | ||
|
|
||
| [204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 | ||
|
|
||
| [400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 | ||
|
|
||
| [401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 | ||
|
|
||
| [403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 | ||
|
|
||
| [404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 | ||
|
|
||
| [409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 | ||
|
|
||
| [412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 | ||
|
|
||
| [422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 | ||
|
|
||
| [429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 | ||
|
|
||
| [500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 | ||
|
|
||
| [504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 | ||
|
|
||
| [JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents | ||
|
|
||
| [JSON API error object]: https://jsonapi.org/format/#error-objects | ||
|
|
||
| # 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> | ||
netramali marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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). | ||
|
|
||
| For other HCP Terraform organizations, refer to the [Team members](/terraform/cloud-docs/api-docs/team-members) API. | ||
|
|
||
| </Note> | ||
|
|
||
| ## 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](/terraform/cloud-docs/api-docs#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 | ||
|
|
||
| ```shell | ||
| $ 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. | ||
|
|
||
| ```json | ||
| { | ||
| "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](/terraform/cloud-docs/api-docs#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 | ||
|
|
||
| ```shell | ||
| $ 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. | ||
|
|
||
| ```json | ||
| { | ||
| "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 | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.