- List users
- Single user
- User creation
- User modification
- Delete authentication identity from user
- User deletion
- List current user
- User status
- Get the status of a user
- Set user status
- Get user preferences
- User preference modification
- User follow
- User counts
- Create Service Account User
- List service account users
- List user projects
- List associations count for user
- 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
- Create a personal access token with limited scopes for the currently authenticated user
- Get user activities
- User memberships
- Disable two factor authentication
- Create a runner linked to a user
- Upload a current user avatar
Users API
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 bothon@example.com
andjon@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
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:
- 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
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
- 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
}
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
- 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.
private_profile
defaults to the value of the
Set profiles of new users to private by default setting.
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 | |
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 | |
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
- 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 | |
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 | |
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
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
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
- 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. |
assigned_merge_requests
| number | Number of merge requests that are active and assigned to the current user. |
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. |
todos
| number | Number of pending to-do items for current user. |
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
- Ability to create a service account user was introduced in GitLab 16.1
- Ability to specify a username or name was introduced in GitLab 16.10.
Creates a service account user. You can specify the account username and name. If you do not specify these attributes, the default name is Service account user
and the username is automatically generated. Available only for administrators.
POST /service_accounts
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
name
| string | no | Name of the user |
username
| string | no | Username of the user |
Example response:
{
"id": 57,
"username": "service_account_6018816a18e515214e0c34c2b33523fc",
"name": "Service account user"
}
List service account users
- Ability to list all service account users introduced in GitLab 17.1.
Prerequisites:
- You must be an administrator of the self-managed instance.
Lists all service account users.
This function takes pagination parameters page
and per_page
to restrict the list of users.
This API endpoint requires the user to be an instance admin.
Example request:
GET /service_accounts
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
order_by
| string | no | Orders list of users by username or id Default is id .
|
sort
| string | no | Specifies sorting by asc or desc . Default is desc .
|
Example response:
[
{
"id": 114,
"username": "service_account_33",
"name": "Service account user"
},
{
"id": 137,
"username": "service_account_34",
"name": "john doe"
}
]
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
- Introduced in GitLab 14.9.
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
- 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"
]
}
}
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
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. 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
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
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.
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
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
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.
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
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
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
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
- Introduced in GitLab 12.4.
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
- Introduced in GitLab 12.4.
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
- 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
See 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:
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
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
- 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:
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
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
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
- The
expires_at
attribute default was introduced in GitLab 16.0.
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
- Introduced in GitLab 16.5.
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
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
- 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:
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
- 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:
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
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
orproject_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": "<access-token>",
"token_expires_at": null
}
Upload a current user avatar
- Introduced in GitLab 17.0.
Upload an avatar to current user.
PUT /user/avatar
Attribute | Type | Required | Description |
---|---|---|---|
avatar
| string | Yes | The file to be uploaded. The ideal image size is 192 x 192 pixels. The maximum file size allowed is 200 KiB. |
To upload an avatar from your file system, use the --form
argument. This causes
cURL to post data using the header Content-Type: multipart/form-data
. The
file=
parameter must point to an image file on your file system and be
preceded by @
. For example:
Example request:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "avatar=@avatar.png" \
--url "https://gitlab.example.com/api/v4/user/avatar"
Returned object:
Returns 400 Bad Request
for file sizes greater than 200 KiB.
If successful, returns 200
and the following
response attributes:
{
"avatar_url": "http://gdk.test:3000/uploads/-/system/user/avatar/76/avatar.png",
}