--- stage: Manage group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group and project members API ## Valid access levels The access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized: - No access (`0`) - Minimal access (`5`) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220203) in GitLab 13.5.) - Guest (`10`) - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) - Owner (`50`) - Only valid to set for groups WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), projects in personal namespaces don't show owner (`50`) permission for owner. ## Limitations The `group_saml_identity` attribute is only visible to a group owner for [SSO enabled groups](../user/group/saml_sso/index.md). The `email` attribute is only visible to a group owner who manages the user through [Group Managed Accounts](../user/group/saml_sso/group_managed_accounts.md). ## List all members of a group or project Gets a list of group or project members viewable by the authenticated user. Returns only direct members and not inherited members through ancestors groups. This function takes pagination parameters `page` and `per_page` to restrict the list of users. ```plaintext GET /groups/:id/members GET /projects/:id/members ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.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 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members" curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members" ``` Example response: ```json [ { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "group_saml_identity": null }, { "id": 2, "username": "john_doe", "name": "John Doe", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "email": "john@example.com", "group_saml_identity": { "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 } } ] ``` ## List all members of a group or project including inherited members Gets a list of group or project members viewable by the authenticated user, including inherited members and permissions through ancestor groups. WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/249523), the users effective `access_level` may actually be higher than returned value when listing group members. This function takes pagination parameters `page` and `per_page` to restrict the list of users. ```plaintext GET /groups/:id/members/all GET /projects/:id/members/all ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.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 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members/all" curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members/all" ``` Example response: ```json [ { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "group_saml_identity": null }, { "id": 2, "username": "john_doe", "name": "John Doe", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30 "email": "john@example.com", "group_saml_identity": { "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 } }, { "id": 3, "username": "foo_bar", "name": "Foo bar", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-11-22T14:13:35Z", "access_level": 30, "group_saml_identity": null } ] ``` ## Get a member of a group or project Gets a member of a group or project. Returns only direct members and not inherited members through ancestor groups. ```plaintext GET /groups/:id/members/:user_id GET /projects/:id/members/:user_id ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members/:user_id" curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members/:user_id" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "access_level": 30, "email": "john@example.com", "created_at": "2012-10-22T14:13:35Z", "expires_at": null, "group_saml_identity": null } ``` ## Get a member of a group or project, including inherited members > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17744) in GitLab 12.4. Gets a member of a group or project, including members inherited through ancestor groups. See the corresponding [endpoint to list all inherited members](#list-all-members-of-a-group-or-project-including-inherited-members) for details. ```plaintext GET /groups/:id/members/all/:user_id GET /projects/:id/members/all/:user_id ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members/all/:user_id" curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members/all/:user_id" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "access_level": 30, "email": "john@example.com", "expires_at": null, "group_saml_identity": null } ``` ## List all billable members of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217384) in GitLab 13.5. Gets a list of group members that count as billable. The list includes members in the subgroup or subproject. NOTE: Unlike other API endpoints, billable members is updated once per day at 12:00 UTC. This function takes [pagination](README.md#pagination) parameters `page` and `per_page` to restrict the list of users. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.7, the `search` and `sort` parameters allow you to search for billable group members by name and sort the results, respectively. ```plaintext GET /groups/:id/billable_members ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | A query string to search for group members by name, username, or email. | | `sort` | string | no | A query string containing parameters that specify the sort attribute and order. See supported values below.| The supported values for the `sort` attribute are: | Value | Description | | ------------------- | ------------------------ | | `access_level_asc` | Access level, ascending | | `access_level_desc` | Access level, descending | | `last_joined` | Last joined | | `name_asc` | Name, ascending | | `name_desc` | Name, descending | | `oldest_joined` | Oldest joined | | `oldest_sign_in` | Oldest sign in | | `recent_sign_in` | Recent sign in | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/billable_members" ``` Example response: ```json [ { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", }, { "id": 2, "username": "john_doe", "name": "John Doe", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "email": "john@example.com" }, { "id": 3, "username": "foo_bar", "name": "Foo bar", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root" } ] ``` ## Add a member to a group or project Adds a member to a group or project. ```plaintext POST /groups/:id/members POST /projects/:id/members ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | ```shell curl --request POST --header "PRIVATE-TOKEN: " --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/members" curl --request POST --header "PRIVATE-TOKEN: " --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/members" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "email": "john@example.com", "group_saml_identity": null } ``` ## Edit a member of a group or project Updates a member of a group or project. ```plaintext PUT /groups/:id/members/:user_id PUT /projects/:id/members/:user_id ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | ```shell curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40" curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members/:user_id?access_level=40" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 40, "email": "john@example.com", "group_saml_identity": null } ``` ### Set override flag for a member of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4875) in GitLab 13.0. By default, the access level of LDAP group members is set to the value specified by LDAP through Group Sync. You can allow access level overrides by calling this endpoint. ```plaintext POST /groups/:id/members/:user_id/override ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 40, "email": "john@example.com", "override": true } ``` ### Remove override for a member of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4875) in GitLab 13.0. Sets the override flag to false and allows LDAP Group Sync to reset the access level to the LDAP-prescribed value. ```plaintext DELETE /groups/:id/members/:user_id/override ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" ``` Example response: ```json { "id": 1, "username": "raymond_smith", "name": "Raymond Smith", "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 40, "email": "john@example.com", "override": false } ``` ## Remove a member from a group or project Removes a user from a group or project. ```plaintext DELETE /groups/:id/members/:user_id DELETE /projects/:id/members/:user_id ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `unassign_issuables` | boolean | false | Flag indicating if the removed member should be unassigned from any issues or merge requests within given group or project | ```shell curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/members/:user_id" curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/:id/members/:user_id" ``` ## Give a group access to a project See [share project with group](projects.md#share-project-with-group)