Users API

List users

Get a list of users.

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

For normal users

GET /users
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "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",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
  }
]

You can also search for users by name, username, or public email by using ?search=. For example. /users?search=John.

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

The namespace_id field in the response was introduced in GitLab 14.10.

GET /users
AttributeTypeRequiredDescription
order_bystringnoReturn users ordered by id, name, username, created_at, or updated_at fields. Default is id
sortstringnoReturn users sorted in asc or desc order. Default is desc
two_factorstringnoFilter users by Two-factor authentication. Filter values are enabled or disabled. By default it returns all users
without_projectsbooleannoFilter users without projects. Default is false, which means that all users are returned, with and without projects.
adminsbooleannoReturn only administrators. Default is false
saml_provider_id numbernoReturn only users created by the specified SAML provider ID. If not included, it returns all users.
[
  {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "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": "",
    "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
  },
  {
    "id": 2,
    "username": "jack_smith",
    "email": "jack@example.com",
    "name": "Jack Smith",
    "state": "blocked",
    "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": "",
    "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
  }
]

Users on GitLab Premium or higher 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 higher 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 lookup users by external UID and provider:

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

For example:

GET /users?extern_uid=1234567&provider=github

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

Single user

Get a single user.

For user

GET /users/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of a user
{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "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": "",
  "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

The namespace_id field in the response was introduced in GitLab 14.10.

GET /users/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of a user

Example Responses:

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "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": "",
  "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
}
note
The plan and trial parameters are only available on GitLab Enterprise Edition.

Users on GitLab Premium or higher 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 higher 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
  ...
}

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

GET /users/:id?with_custom_attributes=true

User creation

Version history
  • 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.
note
From GitLab 13.2, bio defaults to "" instead of null.
POST /users

Parameters:

AttributeRequiredDescription
adminNoUser is an administrator. Valid values are true or false. Defaults to false.
auditor NoUser is an auditor. Valid values are true or false. Defaults to false. Introduced in GitLab 15.3.
avatarNoImage file for user’s avatar
bioNoUser’s biography
can_create_groupNoUser can create groups - true or false
color_scheme_idNoUser’s color scheme for the file viewer (see the user preference docs for more information)
emailYesEmail
extern_uidNoExternal UID
externalNoFlags the user as external - true or false (default)
extra_shared_runners_minutes_limit NoCan be set by administrators only. Additional CI/CD minutes for this user.
force_random_passwordNoSet user password to a random value - true or false (default)
group_id_for_samlNoID of group where SAML has been configured
linkedinNoLinkedIn
locationNoUser’s location
nameYesName
noteNoAdministrator notes for this user
organizationNoOrganization name
passwordNoPassword
private_profileNoUser’s profile is private - true, false (default), or null (is converted to false)
projects_limitNoNumber of projects user can create
providerNoExternal provider name
reset_passwordNoSend user password reset link - true or false(default)
shared_runners_minutes_limit NoCan be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be nil (default; inherit system default), 0 (unlimited), or > 0.
skip_confirmationNoSkip confirmation - true or false (default)
skypeNoSkype ID
theme_idNoGitLab theme for the user (see the user preference docs for more information)
twitterNoTwitter account
usernameYesUsername
view_diffs_file_by_fileNoFlag indicating the user sees only one file diff per page
website_urlNoWebsite URL

User modification

Version history
  • 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.

PUT /users/:id

Parameters:

AttributeRequiredDescription
adminNoUser is an administrator. Valid values are true or false. Defaults to false.
auditor NoUser is an auditor. Valid values are true or false. Defaults to false. Introduced in GitLab 15.3.(default)
avatarNoImage file for user’s avatar
bioNoUser’s biography
can_create_groupNoUser can create groups - true or false
color_scheme_idNoUser’s color scheme for the file viewer (see the user preference docs for more information)
emailNoEmail
extern_uidNoExternal UID
externalNoFlags the user as external - true or false (default)
extra_shared_runners_minutes_limit NoCan be set by administrators only. Additional CI/CD minutes for this user.
group_id_for_samlNoID of group where SAML has been configured
idYesID of the user
linkedinNoLinkedIn
locationNoUser’s location
nameNoName
noteNoAdministration notes for this user
organizationNoOrganization name
passwordNoPassword
private_profileNoUser’s profile is private - true, false (default), or null (is converted to false)
projects_limitNoLimit projects each user can create
providerNoExternal provider name
public_emailNoPublic email of the user (must be already verified)
shared_runners_minutes_limit NoCan be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be nil (default; inherit system default), 0 (unlimited) or > 0.
skip_reconfirmationNoSkip reconfirmation - true or false (default)
skypeNoSkype ID
theme_idNoGitLab theme for the user (see the user preference docs for more information)
twitterNoTwitter account
usernameNoUsername
view_diffs_file_by_fileNoFlag indicating the user sees only one file diff per page
website_urlNoWebsite 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

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

DELETE /users/:id/identities/:provider

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of a user
providerstringyesExternal provider name

User deletion

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:

AttributeTypeRequiredDescription
idintegeryesID of a user
hard_deletebooleannoIf 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 normal users

Gets currently authenticated user.

GET /user
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "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": "",
  "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 higher also see the shared_runners_minutes_limit, extra_shared_runners_minutes_limit parameters.

For administrators

The namespace_id field in the response was introduced in GitLab 14.10.

GET /user

Parameters:

AttributeTypeRequiredDescription
sudointegernoID of a user to make the call in their place
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "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": "",
  "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,
  "note": null
}

Users on GitLab Premium or higher 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 currently signed in 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
AttributeTypeRequiredDescription
id_or_usernamestringyesID 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
AttributeTypeRequiredDescription
emojistringnoName 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.
messagestringnoMessage to set as a status. It can also contain emoji codes. Cannot exceed 100 characters.
clear_status_afterstringnoAutomatically 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

When both parameters emoji and message are empty, the status is cleared. When the clear_status_after parameter is missing from the request, the previously set value for "clear_status_after is cleared.

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 currently 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
}

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
}

Parameters:

AttributeRequiredDescription
view_diffs_file_by_fileYesFlag indicating the user sees only one file diff per page.
show_whitespace_in_diffsYesFlag indicating the user sees whitespace changes in diffs.

User follow

Follow and unfollow users

Follow a user.

POST /users/:id/follow

Unfollow a user.

POST /users/:id/unfollow
AttributeTypeRequiredDescription
idintegeryesID 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",
  "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
AttributeTypeRequiredDescription
idintegeryesID 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",
    "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",
    "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 top right menu) of the currently signed in user.

AttributeTypeDescription
assigned_issuesnumberNumber of issues that are open and assigned to the current user. Added in GitLab 14.2.
assigned_merge_requestsnumberNumber of merge requests that are active and assigned to the current user. Added in GitLab 13.8.
merge_requestsnumber Deprecated in GitLab 13.8. Equivalent to and replaced by assigned_merge_requests.
review_requested_merge_requestsnumberNumber of merge requests that the current user has been requested to review. Added in GitLab 13.8.
todosnumberNumber 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
}

List user projects

Please refer to the List of user projects.

List SSH keys

Get a list of currently authenticated user’s SSH 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
AttributeTypeRequiredDescription
id_or_usernamestringyesID or username of the user to get the SSH keys for.

Single SSH key

Get a single key.

GET /user/keys/:key_id

Parameters:

AttributeTypeRequiredDescription
key_idstringyesID 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

Introduced in GitLab 14.9.

Get a single key for a given user.

GET /users/:id/keys/:key_id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of specified user
key_idintegeryesSSH 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

Creates a new key owned by the currently authenticated user.

POST /user/keys

Parameters:

AttributeTypeRequiredDescription
titlestringyesNew SSH key’s title
keystringyesNew SSH key
expires_atstringnoExpiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
{
  "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"
}

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

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

POST /users/:id/keys

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of specified user
titlestringyesNew SSH key’s title
keystringyesNew SSH key
expires_atstringnoExpiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
note
This also adds an audit event, as described in audit instance events.

Delete SSH key for current user

Deletes key owned by currently 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:

AttributeTypeRequiredDescription
key_idintegeryesSSH key ID

Delete SSH key for given user

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

DELETE /users/:id/keys/:key_id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of specified user
key_idintegeryesSSH key ID

List all GPG keys

Get a list of currently 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 currently authenticated user.

GET /user/gpg_keys/:key_id

Parameters:

AttributeTypeRequiredDescription
key_idintegeryesID 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 currently authenticated user.

POST /user/gpg_keys

Parameters:

AttributeTypeRequiredDescription
keystringyesNew GPG key
curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
     --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"
    }
]

Delete a GPG key

Delete a GPG key owned by currently authenticated user.

DELETE /user/gpg_keys/:key_id

Parameters:

AttributeTypeRequiredDescription
key_idintegeryesID 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:

AttributeTypeRequiredDescription
idintegeryesID 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:

AttributeTypeRequiredDescription
idintegeryesID of the user
key_idintegeryesID 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

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

POST /users/:id/gpg_keys

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of the user
key_idintegeryesID of the GPG key
curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
     --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"
    }
]

Delete a GPG key for a given user

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

DELETE /users/:id/gpg_keys/:key_id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of the user
key_idintegeryesID 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 currently authenticated user’s emails.

note
Due to a bug this endpoint currently does not return the primary email address.
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

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

note
Due to a bug this endpoint currently does not return the primary email address.
GET /users/:id/emails

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of specified user

Single email

Get a single email.

GET /user/emails/:email_id

Parameters:

AttributeTypeRequiredDescription
email_idintegeryesEmail ID
{
  "id": 1,
  "email": "email@example.com",
  "confirmed_at" : "2021-03-26T19:07:56.248Z"
}

Add email

Creates a new email owned by the currently authenticated user.

POST /user/emails

Parameters:

AttributeTypeRequiredDescription
emailstringyesEmail 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

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

POST /users/:id/emails

Parameters:

AttributeTypeRequiredDescription
idstringyesID of specified user
emailstringyesEmail address
skip_confirmationbooleannoSkip confirmation and assume email is verified - true or false (default)

Delete email for current user

Deletes email owned by currently 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/emails/:email_id

Parameters:

AttributeTypeRequiredDescription
email_idintegeryesEmail ID

Delete email for given user

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

DELETE /users/:id/emails/:email_id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of specified user
email_idintegeryesEmail ID

Block user

Blocks the specified user. Available only for administrator.

POST /users/:id/block

Parameters:

AttributeTypeRequiredDescription
idintegeryesID 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

Unblocks the specified user. Available only for administrator.

POST /users/:id/unblock

Parameters:

AttributeTypeRequiredDescription
idintegeryesID 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

Introduced in GitLab 12.4.

Deactivates the specified user. Available only for administrator.

POST /users/:id/deactivate

Parameters:

AttributeTypeRequiredDescription
idintegeryesID 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:
    • Blocked by administrator or by LDAP synchronization.
    • That has any activity in past 90 days. These users cannot be deactivated.
    • That is internal.

Activate user

Introduced in GitLab 12.4.

Activates the specified user. Available only for administrator.

POST /users/:id/activate

Parameters:

AttributeTypeRequiredDescription
idintegeryesID 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

Introduced in GitLab 14.3.

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

Introduced in GitLab 14.3.

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

Please refer to the Events API documentation

Get all impersonation tokens of a user

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:

AttributeTypeRequiredDescription
user_idintegeryesID of the user
statestringnoFilter 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"
   },
   {
      "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"
   }
]

Approve user

Introduced in GitLab 13.7.

Approves the specified user. Available only for administrators.

POST /users/:id/approve

Parameters:

AttributeTypeRequiredDescription
idintegeryesID 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

Introduced in GitLab 14.3.

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

Requires administrators permissions.

It shows a user’s impersonation token.

GET /users/:user_id/impersonation_tokens/:impersonation_token_id

Parameters:

AttributeTypeRequiredDescription
user_idintegeryesID of the user
impersonation_token_idintegeryesID 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

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
AttributeTypeRequiredDescription
user_idintegeryesID of the user
namestringyesName of the impersonation token
expires_atdatenoExpiration date of the impersonation token in ISO format (YYYY-MM-DD)
scopesarrayyesArray 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

Requires administrator access.

It revokes an impersonation token.

DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id

Parameters:

AttributeTypeRequiredDescription
user_idintegeryesID of the user
impersonation_token_idintegeryesID 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

Version history

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
AttributeTypeRequiredDescription
user_idintegeryesID of the user
namestringyesName of the personal access token
expires_atdatenoExpiration date of the personal access token in ISO format (YYYY-MM-DD)
scopesarrayyesArray 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"
}

Get user activities

Pre-requisite:

  • You must be an administrator.

Get the last activity date for all users, sorted from oldest to newest.

The activities that update the timestamp 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 all users in the last 6 months, but this can be amended by using the from parameter.

GET /user/activities

Parameters:

AttributeTypeRequiredDescription
fromstringnoDate 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

Introduced in GitLab 12.8.

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:

AttributeTypeRequiredDescription
idintegeryesID of a specified user
typestringnoFilter 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

Introduced in GitLab 15.2.

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:

AttributeTypeRequiredDescription
idintegeryesID 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.