Skip to content

Member roles API

DETAILS: Tier: Ultimate Offering: SaaS, self-managed

FLAG: On self-managed GitLab, by default these features are not available. To make them available, an administrator can enable the feature flags named admin_group_member and manage_project_access_tokens. On GitLab.com, these features are not available.

List all member roles of a group

Gets a list of group member roles viewable by the authenticated user.

GET /groups/:id/member_roles
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user

If successful, returns 200 and the following response attributes:

Attribute Type Description
[].id integer The ID of the member role.
[].name string The name of the member role.
[].description string The description of the member role.
[].group_id integer The ID of the group that the member role belongs to.
[].base_access_level integer Base access level for member role. Valid values are 10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner).
[].admin_merge_request boolean Permission to admin project merge requests and enables the ability to download_code.
[].admin_terraform_state boolean Permission to admin project terraform state.
[].admin_vulnerability boolean Permission to admin project vulnerabilities.
[].read_code boolean Permission to read project code.
[].read_dependency boolean Permission to read project dependencies.
[].read_vulnerability boolean Permission to read project vulnerabilities.
[].admin_group_member boolean Permission to admin members of a group.
[].manage_project_access_tokens boolean Permission to manage project access tokens.
[].archive_project boolean Permission to archive projects.
[].remove_project boolean Permission to delete projects.
[].manage_group_access_tokens boolean Permission to manage group access tokens.

Example request:

curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/84/member_roles"

Example response:

[
  {
    "id": 2,
    "name": "Custom + code",
    "description": "Custom guest that can read code",
    "group_id": 84,
    "base_access_level": 10,
    "admin_merge_request": false,
    "admin_terraform_state": false,
    "admin_vulnerability": false,
    "read_code": true,
    "read_dependency": false,
    "read_vulnerability": false,
    "manage_group_access_tokens": false,
    "manage_project_access_tokens": false,
    "archive_project": false,
    "remove_project": false
  },
  {
    "id": 3,
    "name": "Guest + security",
    "description": "Custom guest that read and admin security entities",
    "group_id": 84,
    "base_access_level": 10,
    "admin_vulnerability": true,
    "admin_merge_request": false,
    "admin_terraform_state": false,
    "read_code": false,
    "read_dependency": true,
    "read_vulnerability": true,
    "manage_group_access_tokens": false,
    "manage_project_access_tokens": false,
    "archive_project": false,
    "remove_project": false
  }
]

Add a member role to a group

  • Ability to add a name and description when creating a custom role introduced in GitLab 16.3.

Adds a member role to a group.

POST /groups/:id/member_roles

To add a member role to a group, the group must be at root-level (have no parent group).

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user.
name string yes The name of the member role.
description string no The description of the member role.
base_access_level integer yes Base access level for configured role. Valid values are 10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), or 50 (Owner).
admin_merge_request boolean no Permission to admin project merge requests.
admin_terraform_state boolean no Permission to admin project terraform state.
admin_vulnerability boolean no Permission to admin project vulnerabilities.
read_code boolean no Permission to read project code.
read_dependency boolean no Permission to read project dependencies.
read_vulnerability boolean no Permission to read project vulnerabilities.

If successful, returns 201 and the following attributes:

Attribute Type Description
id integer The ID of the member role.
name string The name of the member role.
description string The description of the member role.
group_id integer The ID of the group that the member role belongs to.
base_access_level integer Base access level for member role.
admin_merge_request boolean Permission to admin project merge requests.
admin_terraform_state boolean Permission to admin project terraform state.
admin_vulnerability boolean Permission to admin project vulnerabilities.
read_code boolean Permission to read project code.
read_dependency boolean Permission to read project dependencies.
read_vulnerability boolean Permission to read project vulnerabilities.

Example request:

 curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" --data '{"name" : "Custom guest", "base_access_level" : 10, "read_code" : true}' "https://gitlab.example.com/api/v4/groups/84/member_roles"

Example response:

{
  "id": 3,
  "name": "Custom guest",
  "description": null,
  "group_id": 84,
  "base_access_level": 10,
  "admin_merge_requests": false,
  "admin_vulnerability": false,
  "read_code": true,
  "read_dependency": false,
  "read_vulnerability": false
}

In GitLab 16.3 and later, you can use the API to:

  • Add a name (required) and description (optional) when you create a new custom role.
  • Update an existing custom role's name and description.

Remove member role of a group

Deletes a member role of a group.

DELETE /groups/:id/member_roles/:member_role_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user.
member_role_id integer yes The ID of the member role.

If successful, returns 204 and an empty response.

Example request:

curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/84/member_roles/1"