Skip to content

Users API

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

This documentation has information on API calls, parameters and responses for the Users API.

For information on user activities that update the user event timestamps, see get user activities.

List users

Get a list of users.

This function takes pagination parameters page and per_page to restrict the list of users.

For non-administrator users

GET /users
Attribute Type Required Description
username string no Get a single user with a specific username.
search string no Search for a username.
active boolean no Filters only active users. Default is false.
external boolean no Filters only external users. Default is false.
exclude_external boolean no Filters only non external users. Default is false.
blocked boolean no Filters only blocked users. Default is false.
created_after DateTime no Returns users created after specified time.
created_before DateTime no Returns users created before specified time.
exclude_internal boolean no Filters only non internal users. Default is false.
without_project_bots boolean no Filters user without project bots. Default is false. 
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
  }
]

This endpoint supports keyset pagination. Keyset pagination introduced in GitLab 16.5.

You can also use ?search= to search for users by name, username, or public email. For example, /users?search=John. When you search for a:

  • Public email, you must use the full email address to get an exact match. A search might return a partial match. For example, if you search for the email on@example.com, the search can return both on@example.com and jon@example.com.
  • Name or username, you do not have to get an exact match because this is a fuzzy search.

In addition, you can lookup users by username:

GET /users?username=:username

For example:

GET /users?username=jack_smith

NOTE: Username search is case insensitive.

In addition, you can filter users based on the states blocked and active. It does not support active=false or blocked=false.

GET /users?active=true
GET /users?blocked=true

In addition, you can search for external users only with external=true. It does not support external=false.

GET /users?external=true

GitLab supports bot users such as the alert bot or the support bot. You can exclude the following types of internal users from the users' list with the exclude_internal=true parameter (introduced in GitLab 13.4):

  • Alert bot
  • Support bot

However, this action does not exclude bot users for projects or bot users for groups.

GET /users?exclude_internal=true

In addition, to exclude external users from the users' list, you can use the parameter exclude_external=true.

GET /users?exclude_external=true

To exclude bot users for projects and bot users for groups, you can use the parameter without_project_bots=true.

GET /users?without_project_bots=true

For administrators

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The namespace_id field in the response was introduced in GitLab 14.10.
  • The created_by field in the response was introduced in GitLab 15.6.
  • The scim_identities field in the response introduced in GitLab 16.1.
  • The auditors field in the response introduced in GitLab 16.2.
  • The email_reset_offered_at field in the response introduced in GitLab 16.7.
GET /users

You can use all parameters available for everyone plus these additional parameters available only for administrators.

Attribute Type Required Description
extern_uid string no Get a single user with a specific external authentication provider UID.
provider string no The external provider.
order_by string no Return users ordered by id, name, username, created_at, or updated_at fields. Default is id
sort string no Return users sorted in asc or desc order. Default is desc
two_factor string no Filter users by Two-factor authentication. Filter values are enabled or disabled. By default it returns all users
without_projects boolean no Filter users without projects. Default is false, which means that all users are returned, with and without projects.
admins boolean no Return only administrators. Default is false
auditors boolean no Return only auditor users. Default is false. If not included, it returns all users. Premium and Ultimate only.
saml_provider_id number no Return only users created by the specified SAML provider ID. If not included, it returns all users. Premium and Ultimate only.
skip_ldap boolean no Skip LDAP users. Premium and Ultimate only. 
[
  {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
    "web_url": "http://localhost:3000/john_smith",
    "created_at": "2012-05-23T08:00:58Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 2,
    "projects_limit": 100,
    "current_sign_in_at": "2012-06-02T06:36:55Z",
    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "196.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 1,
    "created_by": null,
    "email_reset_offered_at": null
  },
  {
    "id": 2,
    "username": "jack_smith",
    "email": "jack@example.com",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
    "web_url": "http://localhost:3000/jack_smith",
    "created_at": "2012-05-23T08:01:01Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 3,
    "projects_limit": 100,
    "current_sign_in_at": "2014-03-19T17:54:13Z",
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "10.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 2,
    "created_by": null,
    "email_reset_offered_at": null
  }
]

Users on GitLab Premium or Ultimate also see the shared_runners_minutes_limit, extra_shared_runners_minutes_limit, is_auditor, and using_license_seat parameters.

[
  {
    "id": 1,
    ...
    "shared_runners_minutes_limit": 133,
    "extra_shared_runners_minutes_limit": 133,
    "is_auditor": false,
    "using_license_seat": true
    ...
  }
]

Users on GitLab Premium or Ultimate also see the group_saml provider option and provisioned_by_group_id parameter:

[
  {
    "id": 1,
    ...
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
    ],
    "provisioned_by_group_id": 123789
    ...
  }
]

You can also use ?search= to search for users by name, username, or email. For example, /users?search=John. When you search for a:

  • Email, you must use the full email address to get an exact match. As an administrator, you can search for both public and private email addresses.
  • Name or username, you do not have to get an exact match because this is a fuzzy search.

You can lookup users by external UID and provider:

GET /users?extern_uid=:extern_uid&provider=:provider

For example:

GET /users?extern_uid=1234567&provider=github

Users on GitLab Premium or Ultimate have the scim provider available:

GET /users?extern_uid=1234567&provider=scim

You can search users by creation date time range with:

GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060

You can search for users without projects with: /users?without_projects=true

You can filter by custom attributes with:

GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value

You can include the users' custom attributes in the response with:

GET /users?with_custom_attributes=true

You can use the created_by parameter to see if a user account was created:

If the returned value is null, the account was created by a user who registered an account themselves.

Single user

Get a single user.

For user

Prerequisites:

  • You must be signed in to use this endpoint.
GET /users/:id

Parameters:

Attribute Type Required Description
id integer yes ID of a user 
{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "bot": false,
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "is_followed": false
}

For administrators

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The namespace_id field in the response was introduced in GitLab 14.10.
  • The created_by field in the response was introduced in GitLab 15.6.
  • The email_reset_offered_at field in the response introduced in GitLab 16.7.
GET /users/:id

Parameters:

Attribute Type Required Description
id integer yes ID of a user

Example Responses:

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "plan": "gold",
  "trial": true,
  "sign_in_count": 1337,
  "namespace_id": 1,
  "created_by": null,
  "email_reset_offered_at": null
}

NOTE: The plan and trial parameters are only available on GitLab Enterprise Edition.

Users on GitLab Premium or Ultimate also see the shared_runners_minutes_limit, is_auditor, and extra_shared_runners_minutes_limit parameters.

{
  "id": 1,
  "username": "john_smith",
  "is_auditor": false,
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  ...
}

Users on GitLab.com Premium or Ultimate also see the group_saml option and provisioned_by_group_id parameter:

{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
  ],
  "provisioned_by_group_id": 123789
  ...
}

Users on GitLab.com Premium or Ultimate also see the scim_identities parameter:

{
  ...
  "extra_shared_runners_minutes_limit": null,
  "scim_identities": [
      {"extern_uid": "2435223452345", "group_id": "3", "active": true},
      {"extern_uid": "john.smith", "group_id": "42", "active": false}
    ]
  ...
}

Administrators can use the created_by parameter to see if a user account was created:

If the returned value is null, the account was created by a user who registered an account themselves.

You can include the user's custom attributes in the response with:

GET /users/:id?with_custom_attributes=true

User creation

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The namespace_id field in the response was introduced in GitLab 14.10.
  • Ability to create an auditor user was introduced in GitLab 15.3.

Creates a new user. Note only administrators can create new users. Either password, reset_password, or force_random_password must be specified. If reset_password and force_random_password are both false, then password is required.

force_random_password and reset_password take priority over password. In addition, reset_password and force_random_password can be used together.

NOTE: From GitLab 12.1, private_profile defaults to false. From GitLab 15.8, private_profile defaults to the value determined by this setting.

NOTE: From GitLab 13.2, bio defaults to "" instead of null.

POST /users

Parameters:

Attribute Required Description
admin No User is an administrator. Valid values are true or false. Defaults to false.
auditor No User is an auditor. Valid values are true or false. Defaults to false. Introduced in GitLab 15.3. Premium and Ultimate only.
avatar No Image file for user's avatar
bio No User's biography
can_create_group No User can create top-level groups - true or false
color_scheme_id No User's color scheme for the file viewer (for more information, see the user preference documentation)
commit_email No User's commit email address
email Yes Email
extern_uid No External UID
external No Flags the user as external - true or false (default)
extra_shared_runners_minutes_limit No Can be set by administrators only. Additional compute minutes for this user. Premium and Ultimate only.
force_random_password No Set user password to a random value - true or false (default)
group_id_for_saml No ID of group where SAML has been configured
linkedin No LinkedIn
location No User's location
name Yes Name
note No Administrator notes for this user
organization No Organization name
password No Password
private_profile No User's profile is private - true or false. The default value is determined by this setting.
projects_limit No Number of projects user can create
pronouns No User's pronouns
provider No External provider name
public_email No User's public email address
reset_password No Send user password reset link - true or false(default)
shared_runners_minutes_limit No Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be nil (default; inherit system default), 0 (unlimited), or > 0. Premium and Ultimate only.
skip_confirmation No Skip confirmation - true or false (default)
skype No Skype ID
theme_id No GitLab theme for the user (for more information, see the user preference documentation for more information)
twitter No X (formerly Twitter) account
discord No Discord account
username Yes Username
view_diffs_file_by_file No Flag indicating the user sees only one file diff per page
website_url No Website URL

User modification

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The namespace_id field in the response was introduced in GitLab 14.10.
  • Ability to modify an auditor user was introduced in GitLab 15.3.

Modifies an existing user. Only administrators can change attributes of a user.

The email field is the user's primary email address. You can only change this field to an already-added secondary email address for that user. To add more email addresses to the same user, use the add email function.

PUT /users/:id

Parameters:

Attribute Required Description
admin No User is an administrator. Valid values are true or false. Defaults to false.
auditor No User is an auditor. Valid values are true or false. Defaults to false. Introduced in GitLab 15.3.(default) Premium and Ultimate only.
avatar No Image file for user's avatar
bio No User's biography
can_create_group No User can create groups - true or false
color_scheme_id No User's color scheme for the file viewer (for more information, see the user preference documentation for more information)
commit_email No User's commit email. Set to _private to use the private commit email. Introduced in GitLab 15.5.
email No Email
extern_uid No External UID
external No Flags the user as external - true or false (default)
extra_shared_runners_minutes_limit No Can be set by administrators only. Additional compute minutes for this user. Premium and Ultimate only.
group_id_for_saml No ID of group where SAML has been configured
id Yes ID of the user
linkedin No LinkedIn
location No User's location
name No Name
note No Administration notes for this user
organization No Organization name
password No Password
private_profile No User's profile is private - true or false.
projects_limit No Limit projects each user can create
pronouns No Pronouns
provider No External provider name
public_email No Public email of the user (must be already verified)
shared_runners_minutes_limit No Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be nil (default; inherit system default), 0 (unlimited) or > 0. Premium and Ultimate only.
skip_reconfirmation No Skip reconfirmation - true or false (default)
skype No Skype ID
theme_id No GitLab theme for the user (for more information, see the user preference documentation for more information)
twitter No X (formerly Twitter) account
discord No Discord account
username No Username
view_diffs_file_by_file No Flag indicating the user sees only one file diff per page
website_url No Website URL

On password update, the user is forced to change it upon next login. Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate. For example, when renaming the email address to some existing one.

Delete authentication identity from user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Deletes a user's authentication identity using the provider name associated with that identity. Available only for administrators.

DELETE /users/:id/identities/:provider

Parameters:

Attribute Type Required Description
id integer yes ID of a user
provider string yes External provider name

User deletion

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Deletes a user. Available only for administrators. This returns a 204 No Content status code if the operation was successfully, 404 if the resource was not found or 409 if the user cannot be soft deleted.

DELETE /users/:id

Parameters:

Attribute Type Required Description
id integer yes ID of a user
hard_delete boolean no If true, contributions that would usually be moved to Ghost User are deleted instead, as well as groups owned solely by this user.

List current user

Get current user.

For non-administrator users

Gets the authenticated user.

GET /user
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "pronouns": "he/him",
  "bot": false,
  "work_information": null,
  "followers": 0,
  "following": 0,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "admin@example.com",
}

Users on GitLab Premium or Ultimate also see the shared_runners_minutes_limit, extra_shared_runners_minutes_limit parameters.

For administrators

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The namespace_id field in the response was introduced in GitLab 14.10.
  • The created_by field in the response was introduced in GitLab 15.6.
  • The email_reset_offered_at field in the response introduced in GitLab 16.7.
GET /user

Parameters:

Attribute Type Required Description
sudo integer no ID of a user to make the call in their place 
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": true,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "namespace_id": 1,
  "created_by": null,
  "email_reset_offered_at": null,
  "note": null
}

Users on GitLab Premium or Ultimate also see these parameters:

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • is_auditor
  • provisioned_by_group_id
  • using_license_seat

User status

Get the status of the authenticated user.

GET /user/status
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/status"

Example response:

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

Get the status of a user

Get the status of a user. This endpoint can be accessed without authentication.

GET /users/:id_or_username/status
Attribute Type Required Description
id_or_username string yes ID or username of the user to get a status of 
curl "https://gitlab.example.com/users/janedoe/status"

Example response:

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

Set user status

Set the status of the current user.

PUT /user/status
PATCH /user/status
Attribute Type Required Description
emoji string no Name of the emoji to use as status. If omitted speech_balloon is used. Emoji name can be one of the specified names in the Gemojione index.
message string no Message to set as a status. It can also contain emoji codes. Cannot exceed 100 characters.
clear_status_after string no Automatically clean up the status after a given time interval, allowed values: 30_minutes, 3_hours, 8_hours, 1_day, 3_days, 7_days, 30_days

Difference between PUT and PATCH

When using PUT any parameters that are not passed are set to null and therefore cleared. When using PATCH any parameters that are not passed are ignored. Explicitly pass null to clear a field.

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" \
     --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status"

Example responses

{
  "emoji":"coffee",
  "message":"I crave coffee",
  "message_html": "I crave coffee",
  "clear_status_at":"2021-02-15T10:49:01.311Z"
}

Get user preferences

Get a list of the authenticated user's preferences.

GET /user/preferences

Example response:

{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

Parameters:

  • none

User preference modification

Update the current user's preferences.

PUT /user/preferences
{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

Parameters:

Attribute Required Description
view_diffs_file_by_file Yes Flag indicating the user sees only one file diff per page.
show_whitespace_in_diffs Yes Flag indicating the user sees whitespace changes in diffs.
pass_user_identities_to_ci_jwt Yes Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see Token Payload.

User follow

Follow and unfollow users

Follow a user.

POST /users/:id/follow

Unfollow a user.

POST /users/:id/unfollow
Attribute Type Required Description
id integer yes ID of the user to follow 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow"

Example response:

{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith"
}

Followers and following

Get the followers of a user.

GET /users/:id/followers

Get the list of users being followed.

GET /users/:id/following
Attribute Type Required Description
id integer yes ID of the user to follow 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>"  "https://gitlab.example.com/users/3/followers"

Example response:

[
  {
    "id": 2,
    "name": "Lennie Donnelly",
    "username": "evette.kilback",
    "state": "active",
    "locked": false,
    "avatar_url": "https://www.gravatar.com/avatar/7955171a55ac4997ed81e5976287890a?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/evette.kilback"
  },
  {
    "id": 4,
    "name": "Serena Bradtke",
    "username": "cammy",
    "state": "active",
    "locked": false,
    "avatar_url": "https://www.gravatar.com/avatar/a2daad869a7b60d3090b7b9bef4baf57?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/cammy"
  }
]

User counts

Get the counts (same as in the upper-right menu) of the authenticated user.

Attribute Type Description
assigned_issues number Number of issues that are open and assigned to the current user. Added in GitLab 14.2.
assigned_merge_requests number Number of merge requests that are active and assigned to the current user. Added in GitLab 13.8.
merge_requests number Deprecated in GitLab 13.8. Equivalent to and replaced by assigned_merge_requests.
review_requested_merge_requests number Number of merge requests that the current user has been requested to review. Added in GitLab 13.8.
todos number Number of pending to-do items for current user. Added in GitLab 14.2. 
GET /user_counts
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"

Example response:

{
  "merge_requests": 4,
  "assigned_issues": 15,
  "assigned_merge_requests": 11,
  "review_requested_merge_requests": 0,
  "todos": 1
}

Create Service Account User

DETAILS: Tier: Premium, Ultimate Offering: Self-managed

  • Ability to create a service account user was introduced in GitLab 16.1

Creates a service account user with an auto-generated email address and username. Available only for administrators.

POST /service_accounts
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"

List user projects

See the list of user projects.

List associations count for user

Get a list of a specified user's count of:

  • Projects.
  • Groups.
  • Issues.
  • Merge requests.

Administrators can query any user, but non-administrators can only query themselves.

GET /users/:id/associations_count

Parameters:

Attribute Type Required Description
id integer yes ID of a user

Example response:

{
  "groups_count": 2,
  "projects_count": 3,
  "issues_count": 8,
  "merge_requests_count": 5
}

List SSH keys

Get a list of the authenticated user's SSH keys.

This function takes pagination parameters page and per_page to restrict the list of keys.

GET /user/keys
[
  {
    "id": 1,
    "title": "Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
  },
  {
    "id": 3,
    "title": "Another Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
  }
]

Parameters:

  • none

List SSH keys for user

Get a list of a specified user's SSH keys.

GET /users/:id_or_username/keys
Attribute Type Required Description
id_or_username string yes ID or username of the user to get the SSH keys for.

Single SSH key

Get a single key.

GET /user/keys/:key_id

Parameters:

Attribute Type Required Description
key_id string yes ID of an SSH key 
{
  "id": 1,
  "title": "Public key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
}

Single SSH key for given user

Get a single key for a given user.

GET /users/:id/keys/:key_id

Parameters:

Attribute Type Required Description
id integer yes ID of specified user
key_id integer yes SSH key ID 
{
  "id": 1,
  "title": "Public key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
}

Add SSH key

  • The usage_type parameter was introduced in GitLab 15.7.

Creates a new key owned by the authenticated user.

POST /user/keys

Parameters:

Attribute Type Required Description
title string yes New SSH key's title
key string yes New SSH key
expires_at string no Expiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
usage_type string no Scope of usage for the SSH key: auth, signing or auth_and_signing. Default: auth_and_signing 
{
  "title": "ABC",
  "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
  "expires_at": "2016-01-21T00:00:00.000Z",
  "usage_type": "auth"
}

Returns a created key with status 201 Created on success. If an error occurs a 400 Bad Request is returned with a message explaining the error:

{
  "message": {
    "fingerprint": [
      "has already been taken"
    ],
    "key": [
      "has already been taken"
    ]
  }
}

Add SSH key for user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

  • The usage_type parameter was introduced in GitLab 15.7.

Create new key owned by specified user. Available only for administrator.

POST /users/:id/keys

Parameters:

Attribute Type Required Description
id integer yes ID of specified user
title string yes New SSH key's title
key string yes New SSH key
expires_at string no Expiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
usage_type string no Scope of usage for the SSH key: auth, signing or auth_and_signing. Default: auth_and_signing 
{
  "title": "ABC",
  "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
  "expires_at": "2016-01-21T00:00:00.000Z",
  "usage_type": "auth"
}

Returns a created key with status 201 Created on success. If an error occurs a 400 Bad Request is returned with a message explaining the error:

{
  "message": {
    "fingerprint": [
      "has already been taken"
    ],
    "key": [
      "has already been taken"
    ]
  }
}

NOTE: This also adds an audit event.

Delete SSH key for current user

Deletes key owned by the authenticated user.

This returns a 204 No Content status code if the operation was successfully or 404 if the resource was not found.

DELETE /user/keys/:key_id

Parameters:

Attribute Type Required Description
key_id integer yes SSH key ID

Delete SSH key for given user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Deletes key owned by a specified user. Available only for administrator.

DELETE /users/:id/keys/:key_id

Parameters:

Attribute Type Required Description
id integer yes ID of specified user
key_id integer yes SSH key ID

List all GPG keys

Get a list of the authenticated user's GPG keys.

GET /user/gpg_keys
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys"

Example response:

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

Get a specific GPG key

Get a specific GPG key of authenticated user.

GET /user/gpg_keys/:key_id

Parameters:

Attribute Type Required Description
key_id integer yes ID of the GPG key 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"

Example response:

  {
      "id": 1,
      "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
      "created_at": "2017-09-05T09:17:46.264Z"
  }

Add a GPG key

Creates a new GPG key owned by the authenticated user.

POST /user/gpg_keys

Parameters:

Attribute Type Required Description
key string yes New GPG key 

export KEY="$( gpg --armor --export <your_gpg_key_id>)"

curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK-----
> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj
> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O
> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa
> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO
> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57
> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp
> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV
> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/
> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5
> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4
> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn
> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp
> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=
> =XQoy
> -----END PGP PUBLIC KEY BLOCK-----" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys"

Example response:

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

Delete a GPG key

Delete a GPG key owned by the authenticated user.

DELETE /user/gpg_keys/:key_id

Parameters:

Attribute Type Required Description
key_id integer yes ID of the GPG key 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"

Returns 204 No Content on success or 404 Not Found if the key cannot be found.

List all GPG keys for given user

Get a list of a specified user's GPG keys. This endpoint can be accessed without authentication.

GET /users/:id/gpg_keys

Parameters:

Attribute Type Required Description
id integer yes ID of the user 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys"

Example response:

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

Get a specific GPG key for a given user

Get a specific GPG key for a given user. Introduced in GitLab 13.5, this endpoint can be accessed without administrator authentication.

GET /users/:id/gpg_keys/:key_id

Parameters:

Attribute Type Required Description
id integer yes ID of the user
key_id integer yes ID of the GPG key 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"

Example response:

  {
      "id": 1,
      "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
      "created_at": "2017-09-05T09:17:46.264Z"
  }

Add a GPG key for a given user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Create new GPG key owned by the specified user. Available only for administrator.

POST /users/:id/gpg_keys

Parameters:

Attribute Type Required Description
id integer yes ID of the user
key_id integer yes ID of the GPG key 
curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK-----
> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj
> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O
> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa
> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO
> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57
> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp
> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV
> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/
> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5
> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4
> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn
> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp
> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=
> =XQoy
> -----END PGP PUBLIC KEY BLOCK-----" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys"

Example response:

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

Delete a GPG key for a given user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Delete a GPG key owned by a specified user. Available only for administrator.

DELETE /users/:id/gpg_keys/:key_id

Parameters:

Attribute Type Required Description
id integer yes ID of the user
key_id integer yes ID of the GPG key 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"

List emails

Get a list of the authenticated user's emails.

NOTE: This endpoint does not return the primary email address, but issue 25077 proposes to change this behavior.

GET /user/emails
[
  {
    "id": 1,
    "email": "email@example.com",
    "confirmed_at" : "2021-03-26T19:07:56.248Z"
  },
  {
    "id": 3,
    "email": "email2@example.com",
    "confirmed_at" : null
  }
]

Parameters:

  • none

List emails for user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Get a list of a specified user's emails. Available only for administrator

NOTE: This endpoint does not return the primary email address, but issue 25077 proposes to change this behavior.

GET /users/:id/emails

Parameters:

Attribute Type Required Description
id integer yes ID of specified user

Single email

Get a single email.

GET /user/emails/:email_id

Parameters:

Attribute Type Required Description
email_id integer yes Email ID 
{
  "id": 1,
  "email": "email@example.com",
  "confirmed_at" : "2021-03-26T19:07:56.248Z"
}

Add email

Creates a new email owned by the authenticated user.

POST /user/emails

Parameters:

Attribute Type Required Description
email string yes Email address 
{
  "id": 4,
  "email": "email@example.com",
  "confirmed_at" : "2021-03-26T19:07:56.248Z"
}

Returns a created email with status 201 Created on success. If an error occurs a 400 Bad Request is returned with a message explaining the error:

{
  "message": {
    "email": [
      "has already been taken"
    ]
  }
}

Add email for user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Create new email owned by specified user. Available only for administrator

POST /users/:id/emails

Parameters:

Attribute Type Required Description
id string yes ID of specified user
email string yes Email address
skip_confirmation boolean no Skip confirmation and assume email is verified - true or false (default)

Delete email for current user

Deletes the specified email address owned by the authenticated user. Cannot be used to delete a primary email address.

If the deleted email address is used for any user emails, those user emails are sent to the primary email address instead.

NOTE: Because of known issue, group notifications are still sent to the deleted email address.

DELETE /user/emails/:email_id

Parameters:

Attribute Type Required Description
email_id integer yes Email ID

Returns:

  • 204 No Content if the operation was successful.
  • 404 if the resource was not found.

Delete email for given user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Prerequisites:

  • You must be an administrator of a self-managed GitLab instance.

Deletes an email address owned by a specified user. This cannot delete a primary email address.

DELETE /users/:id/emails/:email_id

Parameters:

Attribute Type Required Description
id integer yes ID of specified user
email_id integer yes Email ID

Block user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Blocks the specified user. Available only for administrator.

POST /users/:id/block

Parameters:

Attribute Type Required Description
id integer yes ID of specified user

Returns:

  • 201 OK on success.
  • 404 User Not Found if user cannot be found.
  • 403 Forbidden when trying to block:
    • A user that is blocked through LDAP.
    • An internal user.

Unblock user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Unblocks the specified user. Available only for administrator.

POST /users/:id/unblock

Parameters:

Attribute Type Required Description
id integer yes ID of specified user

Returns 201 OK on success, 404 User Not Found is user cannot be found or 403 Forbidden when trying to unblock a user blocked by LDAP synchronization.

Deactivate user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Deactivates the specified user. Available only for administrator.

POST /users/:id/deactivate

Parameters:

Attribute Type Required Description
id integer yes ID of specified user

Returns:

  • 201 OK on success.
  • 404 User Not Found if user cannot be found.
  • 403 Forbidden when trying to deactivate a user that is:
    • Blocked by administrator or by LDAP synchronization.
    • Not dormant.
    • Internal.

Activate user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Activates the specified user. Available only for administrator.

POST /users/:id/activate

Parameters:

Attribute Type Required Description
id integer yes ID of specified user

Returns:

  • 201 OK on success.
  • 404 User Not Found if the user cannot be found.
  • 403 Forbidden if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization.

Ban user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Bans the specified user. Available only for administrator.

POST /users/:id/ban

Parameters:

  • id (required) - ID of specified user

Returns:

  • 201 OK on success.
  • 404 User Not Found if user cannot be found.
  • 403 Forbidden when trying to ban a user that is not active.

Unban user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Unbans the specified user. Available only for administrator.

POST /users/:id/unban

Parameters:

  • id (required) - ID of specified user

Returns:

  • 201 OK on success.
  • 404 User Not Found if the user cannot be found.
  • 403 Forbidden when trying to unban a user that is not banned.

Get user contribution events

See the Events API documentation

Get all impersonation tokens of a user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Requires administrator access.

It retrieves every impersonation token of the user. Use the pagination parameters page and per_page to restrict the list of impersonation tokens.

GET /users/:user_id/impersonation_tokens

Parameters:

Attribute Type Required Description
user_id integer yes ID of the user
state string no Filter tokens based on state (all, active, inactive) 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

Example response:

[
   {
      "active" : true,
      "user_id" : 2,
      "scopes" : [
         "api"
      ],
      "revoked" : false,
      "name" : "mytoken",
      "id" : 2,
      "created_at" : "2017-03-17T17:18:09.283Z",
      "impersonation" : true,
      "expires_at" : "2017-04-04",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   },
   {
      "active" : false,
      "user_id" : 2,
      "scopes" : [
         "read_user"
      ],
      "revoked" : true,
      "name" : "mytoken2",
      "created_at" : "2017-03-17T17:19:28.697Z",
      "id" : 3,
      "impersonation" : true,
      "expires_at" : "2017-04-14",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   }
]

Approve user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Approves the specified user. Available only for administrators.

POST /users/:id/approve

Parameters:

Attribute Type Required Description
id integer yes ID of specified user 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve"

Returns:

  • 201 Created on success.
  • 404 User Not Found if user cannot be found.
  • 403 Forbidden if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization.
  • 409 Conflict if the user has been deactivated.

Example Responses:

{ "message": "Success" }
{ "message": "404 User Not Found" }
{ "message": "The user you are trying to approve is not pending approval" }

Reject user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Rejects specified user that is pending approval. Available only for administrators.

POST /users/:id/reject

Parameters:

  • id (required) - ID of specified user
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/reject"

Returns:

  • 200 OK on success.
  • 403 Forbidden if not authenticated as an administrator.
  • 404 User Not Found if user cannot be found.
  • 409 Conflict if user is not pending approval.

Example Responses:

{ "message": "Success" }
{ "message": "404 User Not Found" }
{ "message": "User does not have a pending request" }

Get an impersonation token of a user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Requires administrators permissions.

It shows a user's impersonation token.

GET /users/:user_id/impersonation_tokens/:impersonation_token_id

Parameters:

Attribute Type Required Description
user_id integer yes ID of the user
impersonation_token_id integer yes ID of the impersonation token 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2"

Example response:

{
   "active" : true,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "revoked" : false,
   "name" : "mytoken",
   "id" : 2,
   "created_at" : "2017-03-17T17:18:09.283Z",
   "impersonation" : true,
   "expires_at" : "2017-04-04"
}

Create an impersonation token

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Requires administrator access. Token values are returned once. Make sure you save it because you can't access it again.

It creates a new impersonation token. Only administrators can do this. You are only able to create impersonation tokens to impersonate the user and perform both API calls and Git reads and writes. The user can't see these tokens in their profile settings page.

POST /users/:user_id/impersonation_tokens
Attribute Type Required Description
user_id integer yes ID of the user
name string yes Name of the impersonation token
expires_at date yes Expiration date of the impersonation token in ISO format (YYYY-MM-DD)
scopes array yes Array of scopes of the impersonation token (api, read_user) 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

Example response:

{
   "id" : 2,
   "revoked" : false,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "token" : "EsMo-vhKfXGwX9RKrwiy",
   "active" : true,
   "impersonation" : true,
   "name" : "mytoken",
   "created_at" : "2017-03-17T17:18:09.283Z",
   "expires_at" : "2017-04-04"
}

Revoke an impersonation token

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Requires administrator access.

It revokes an impersonation token.

DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id

Parameters:

Attribute Type Required Description
user_id integer yes ID of the user
impersonation_token_id integer yes ID of the impersonation token 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"

Create a personal access token

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Use this API to create a new personal access token. Token values are returned once so, make sure you save it as you can't access it again. This API can only be used by GitLab administrators.

POST /users/:user_id/personal_access_tokens
Attribute Type Required Description
user_id integer yes ID of the user
name string yes Name of the personal access token
expires_at date no Expiration date of the access token in ISO format (YYYY-MM-DD). If no date is set, the expiration is set to the maximum allowable lifetime of an access token.
scopes array yes Array of scopes of the personal access token. See personal access token scopes for possible values. 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens"

Example response:

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "scopes": [
        "api"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-12-31",
    "token": "ggbfKkC4n-Lujy8jwCR2"
}

Create a personal access token with limited scopes for the currently authenticated user

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Use this API to create a new personal access token for the currently authenticated user. For security purposes, the token:

  • Is limited to the k8s_proxy scope. This scope grants permission to perform Kubernetes API calls using the agent for Kubernetes.
  • By default, expires at the end of the day it was created on.

Token values are returned once, so make sure you save the token as you cannot access it again.

POST /user/personal_access_tokens
Attribute Type Required Description
name string yes Name of the personal access token
scopes array yes Array of scopes of the personal access token. Possible values are k8s_proxy
expires_at array no Expiration date of the access token in ISO format (YYYY-MM-DD). If no date is set, the expiration is at the end of the current day. The expiration is subject to the maximum allowable lifetime of an access token. 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "scopes[]=k8s_proxy" "https://gitlab.example.com/api/v4/user/personal_access_tokens"

Example response:

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "scopes": [
        "k8s_proxy"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-10-15",
    "token": "<your_new_access_token>"
}

Get user activities

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Pre-requisite:

  • You must be an administrator to view the activity of users with private profiles.

Get the last activity date for users with public profiles, sorted from oldest to newest.

The activities that update the user event timestamps (last_activity_on and current_sign_in_at) are:

  • Git HTTP/SSH activities (such as clone, push)
  • User logging in to GitLab
  • User visiting pages related to dashboards, projects, issues, and merge requests (introduced in GitLab 11.8)
  • User using the API
  • User using the GraphQL API

By default, it shows the activity for users with public profiles in the last 6 months, but this can be amended by using the from parameter.

GET /user/activities

Parameters:

Attribute Type Required Description
from string no Date string in the format YEAR-MM-DD. For example, 2016-03-11. Defaults to 6 months ago. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/activities"

Example response:

[
  {
    "username": "user1",
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
  },
  {
    "username": "user2",
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
  },
  {
    "username": "user3",
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
  }
]

last_activity_at is deprecated. Use last_activity_on instead.

User memberships

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Pre-requisite:

  • You must be an administrator.

Lists all projects and groups a user is a member of. It returns the source_id, source_name, source_type, and access_level of a membership. Source can be of type Namespace (representing a group) or Project. The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included. Access levels are represented by an integer value. For more details, read about the meaning of access level values.

GET /users/:id/memberships

Parameters:

Attribute Type Required Description
id integer yes ID of a specified user
type string no Filter memberships by type. Can be either Project or Namespace

Returns:

  • 200 OK on success.
  • 404 User Not Found if user can't be found.
  • 403 Forbidden when not requested by an administrator.
  • 400 Bad Request when requested type is not supported.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/:user_id/memberships"

Example response:

[
  {
    "source_id": 1,
    "source_name": "Project one",
    "source_type": "Project",
    "access_level": "20"
  },
  {
    "source_id": 3,
    "source_name": "Group three",
    "source_type": "Namespace",
    "access_level": "20"
  }
]

Disable two factor authentication

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

Pre-requisite:

  • You must be an administrator.

Disables two factor authentication (2FA) for the specified user.

Administrators cannot disable 2FA for their own user account or other administrators using the API. Instead, they can disable an administrator's 2FA using the Rails console.

PATCH /users/:id/disable_two_factor

Parameters:

Attribute Type Required Description
id integer yes ID of the user 
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1/disable_two_factor"

Returns:

  • 204 No content on success.
  • 400 Bad request if two factor authentication is not enabled for the specified user.
  • 403 Forbidden if not authenticated as an administrator.
  • 404 User Not Found if user cannot be found.

Create a runner linked to a user

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

Creates a runner linked to the current user.

Prerequisites:

  • You must be an administrator or have the Owner role of the target namespace or project.
  • For instance_type, you must be an administrator of the GitLab instance.
  • For group_type or project_type with an Owner role, an administrator must not have enabled restrict runner registration.
  • An access token with the create_runner scope.

Be sure to copy or save the token in the response, the value cannot be retrieved again.

POST /user/runners
Attribute Type Required Description
runner_type string yes Specifies the scope of the runner; instance_type, group_type, or project_type.
group_id integer no The ID of the group that the runner is created in. Required if runner_type is group_type.
project_id integer no The ID of the project that the runner is created in. Required if runner_type is project_type.
description string no Description of the runner.
paused boolean no Specifies if the runner should ignore new jobs.
locked boolean no Specifies if the runner should be locked for the current project.
run_untagged boolean no Specifies if the runner should handle untagged jobs.
tag_list string array no A list of runner tags.
access_level string no The access level of the runner; not_protected or ref_protected.
maximum_timeout integer no Maximum timeout that limits the amount of time (in seconds) that runners can run jobs.
maintenance_note string no Free-form maintenance notes for the runner (1024 characters). 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "runner_type=instance_type" \
     "https://gitlab.example.com/api/v4/user/runners"

Example response:

{
    "id": 9171,
    "token": "glrt-kyahzxLaj4Dc1jQf4xjX",
    "token_expires_at": null
}