diff options
Diffstat (limited to 'doc/api/members.md')
| -rw-r--r-- | doc/api/members.md | 94 |
1 files changed, 80 insertions, 14 deletions
diff --git a/doc/api/members.md b/doc/api/members.md index ce276487f21..bc476980d2d 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -65,7 +65,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" }, { "id": 2, @@ -81,7 +82,8 @@ Example response: "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 - } + }, + "membership_state": "active" } ] ``` @@ -107,6 +109,7 @@ GET /projects/:id/members/all | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | +| `state` | string | no | Filter results by member state, one of `awaiting`, `active` or `created` **(PREMIUM)** | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/all" @@ -126,7 +129,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" }, { "id": 2, @@ -142,7 +146,8 @@ Example response: "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 - } + }, + "membership_state": "active" }, { "id": 3, @@ -153,7 +158,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-11-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ] ``` @@ -191,7 +197,8 @@ Example response: "email": "john@example.com", "created_at": "2012-10-22T14:13:35Z", "expires_at": null, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ``` @@ -229,7 +236,8 @@ Example response: "access_level": 30, "email": "john@example.com", "expires_at": null, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ``` @@ -421,7 +429,6 @@ POST /projects/:id/members | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | | `invite_source` | string | no | The source of the invitation that starts the member creation process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327120). | -| `areas_of_focus` | string | no | Areas the inviter wants the member to focus upon. | | `tasks_to_be_done` | array of strings | no | Tasks the inviter wants the member to focus on. The tasks are added as issues to a specified project. The possible values are: `ci`, `code` and `issues`. If specified, requires `tasks_project_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | | `tasks_project_id` | integer | no | The project ID in which to create the task issues. If specified, requires `tasks_to_be_done`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | @@ -589,26 +596,26 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/members/:user_id" ``` -## Approve a member for a group +## Approve a member for a group -Approves a pending user for a group and its subgroups and projects. +Approves a pending user for a group and its subgroups and projects. ```plaintext -PUT /groups/:id/members/:user_id/approve +PUT /groups/:id/members/:member_id/approve ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | -| `user_id` | integer | yes | The user ID of the member | +| `member_id` | integer | yes | The ID of the member | Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/approve" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:member_id/approve" ``` -## Approve all pending members for a group +## Approve all pending members for a group Approves all pending users for a group and its subgroups and projects. @@ -626,6 +633,65 @@ Example request: curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/approve_all" ``` +## List pending members of a group and its subgroups and projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332596) in GitLab 14.6. + +For a group and its subgroups and projects, get a list of all members in an `awaiting` state and those who are invited but do not have a GitLab account. + +This request returns all matching group and project members from all groups and projects in the root group's hierarchy. + +When the member is an invited user that has not signed up for a GitLab account yet, the invited email address is returned. + +This API endpoint works on top-level groups only. It does not work on subgroups. + +This API endpoint requires permission to administer members for the group. + +This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of members. + +```plaintext +GET /groups/:id/pending_members +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/pending_members" +``` + +Example response: + +```json +[ + { + "id": 168, + "name": "Alex Garcia", + "username": "alex_garcia", + "email": "alex@example.com", + "avatar_url": "http://example.com/uploads/user/avatar/1/cd8.jpeg", + "web_url": "http://example.com/alex_garcia", + "approved": false, + "invited": false + }, + { + "id": 169, + "email": "sidney@example.com", + "avatar_url": "http://gravatar.com/../e346561cd8.jpeg", + "approved": false, + "invited": true + }, + { + "id": 170, + "email": "zhang@example.com", + "avatar_url": "http://gravatar.com/../e32131cd8.jpeg", + "approved": true, + "invited": true + } +] +``` + ## Give a group access to a project See [share project with group](projects.md#share-project-with-group) |