- List users
- Single user
- User creation
- User modification
- Delete authentication identity from user
- User deletion
- List current user (for normal users)
- List current user (for admins)
- User status
- Get the status of a user
- Set user status
- Get user preferences
- User preference modification
- User Follow
- User counts
- List user projects
- List SSH keys
- List SSH keys for user
- Single SSH key
- Single SSH key for given user
- Add SSH key
- Add SSH key for user
- Delete SSH key for current user
- Delete SSH key for given user
- List all GPG keys
- Get a specific GPG key
- Add a GPG key
- Delete a GPG key
- List all GPG keys for given user
- Get a specific GPG key for a given user
- Add a GPG key for a given user
- Delete a GPG key for a given user
- List emails
- List emails for user
- Single email
- Add email
- Add email for user
- Delete email for current user
- Delete email for given user
- Block user
- Unblock user
- Deactivate user
- Activate user
- Ban user
- Unban user
- Get user contribution events
- Get all impersonation tokens of a user
- Approve user
- Reject user
- Get an impersonation token of a user
- Create an impersonation token
- Revoke an impersonation token
- Create a personal access token
- Get user activities (admin only)
- User memberships (admin only)
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
In addition, you can filter users based on the states blocked and active.
It does not support active=false or blocked=false. The list of billable users
is the total number of users minus the blocked users.
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 However, this action does not exclude bot users for projects
or bot users for groups.
In addition, to exclude external users from the users’ list, you can use the parameter To exclude bot users for projects
and bot users for groups, you can use the
parameter The Users on group_saml provider option and You can lookup users by external UID and provider:
For example:
You can search users by creation date time range with:
You can search for users without projects with: You can filter by custom attributes with:
You can include the users’ custom attributes in the response with:
Get a single user.
Parameters:
The Parameters:
Example Responses:
Users on shared_runners_minutes_limit, Users on group_saml option and You can include the user’s custom attributes in the response with:
The Creates a new user. Note only administrators can create new
users. Either Parameters:
The Modifies an existing user. Only administrators can change attributes of a user.
Parameters:
On password update, the user is forced to change it upon next login.
Note, at the moment this method does only return a Deletes a user’s authentication identity using the provider name associated with that identity. Available only for administrators.
Parameters:
Deletes a user. Available only for administrators.
This returns a Parameters:
Gets currently authenticated user.
Users on List current user (for admins)
The Parameters:
Users on
Get the status of the currently signed in user.
Example response:
Get the status of a user. This endpoint can be accessed without authentication.
Example response:
Set the status of the current user.
When both parameters Example responses
Get a list of currently authenticated user’s preferences.
Example response:
Parameters:
Update the current user’s preferences.
Parameters:
Follow a user.
Unfollow a user.
Example response:
Get the followers of a user.
Get the list of users being followed.
Example response:
Get the counts (same as in top right menu) of the currently signed in user.
exclude_internal=true parameter
(
GET /users?exclude_internal=true
exclude_external=true.
GET /users?exclude_external=true
without_project_bots=true.
GET /users?without_project_bots=true
For admins
namespace_id field in the response was
GET /users
Attribute
Type
Required
Description
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
saml_provider_id
number
no
Return 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
}
]
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
...
}
]
GET /users?extern_uid=:extern_uid&provider=:provider
GET /users?extern_uid=1234567&provider=github
GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060
/users?without_projects=true
GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value
GET /users?with_custom_attributes=true
Single user
For user
GET /users/:id
Attribute
Type
Required
Description
id
integer
yes
The ID 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"
}
For admin
namespace_id field in the response was
GET /users/:id
Attribute
Type
Required
Description
id
integer
yes
The ID of a 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",
"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
}
plan and trial parameters are only available on GitLab Enterprise Edition.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,
...
}
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
...
}
GET /users/:id?with_custom_attributes=true
User creation
namespace_id field in the response was
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.
null.POST /users
Attribute
Required
Description
admin
No
User is admin - true or false (default)
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 (see the user preference docs for more information)
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 CI/CD minutes for this user.
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
Admin notes for this user
organization
No
Organization name
password
No
Password
private_profile
No
User’s profile is private - true, false (default), or null (is converted to false)
projects_limit
No
Number of projects user can create
provider
No
External provider name
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 CI/CD minutes for this user. Can be nil (default; inherit system default), 0 (unlimited), or > 0.
skip_confirmation
No
Skip confirmation - true or false (default)
skype
No
Skype ID
theme_id
No
The GitLab theme for the user (see the user preference docs for more information)
twitter
No
Twitter 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
namespace_id field in the response was
PUT /users/:id
Attribute
Required
Description
admin
No
User is admin - true or false (default)
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 (see the user preference docs for more information)
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 CI/CD minutes for this user.
group_id_for_saml
No
ID of group where SAML has been configured
id
Yes
The ID of the user
linkedin
No
LinkedIn
location
No
User’s location
name
No
Name
note
No
Admin notes for this user
organization
No
Organization name
password
No
Password
private_profile
No
User’s profile is private - true, false (default), or null (is converted to false)
projects_limit
No
Limit projects each user can create
provider
No
External provider name
public_email
No
The public email of the user (must be already verified)
shared_runners_minutes_limit
No
Can 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_reconfirmation
No
Skip reconfirmation - true or false (default)
skype
No
Skype ID
theme_id
No
The GitLab theme for the user (see the user preference docs for more information)
twitter
No
Twitter 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
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
DELETE /users/:id/identities/:provider
Attribute
Type
Required
Description
id
integer
yes
The ID of a user
provider
string
yes
External provider name
User deletion
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
Attribute
Type
Required
Description
id
integer
yes
The 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 (for normal users)
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",
}
namespace_id field in the response was
GET /user
Attribute
Type
Required
Description
sudo
integer
no
the 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",
"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
}
shared_runners_minutes_limit
extra_shared_runners_minutes_limit
is_auditor
provisioned_by_group_id
using_license_seat
User status
GET /user/status
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status"
{
"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 /users/:id_or_username/status
Attribute
Type
Required
Description
id_or_username
string
yes
The ID or username of the user to get a status of
curl "https://gitlab.example.com/users/janedoe/status"
{
"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
PUT /user/status
Attribute
Type
Required
Description
emoji
string
no
The 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 .
message
string
no
The message to set as a status. It can also contain emoji codes.
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
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"
{
"emoji":"coffee",
"message":"I crave coffee",
"message_html": "I crave coffee",
"clear_status_at":"2021-02-15T10:49:01.311Z"
}
Get user preferences
GET /user/preferences
{
"id": 1,
"user_id": 1
"view_diffs_file_by_file": true,
"show_whitespace_in_diffs": false
}
User preference modification
PUT /user/preferences
{
"id": 1,
"user_id": 1
"view_diffs_file_by_file": true,
"show_whitespace_in_diffs": false
}
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.
User Follow
Follow and unfollow users
POST /users/:id/follow
POST /users/:id/unfollow
Attribute
Type
Required
Description
id
integer
yes
The ID of the user to follow
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow"
{
"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 /users/:id/followers
GET /users/:id/following
Attribute
Type
Required
Description
id
integer
yes
The ID of the user to follow
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/followers"
[
{
"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