2017-05-10 18:48:07 +00:00
# Users API
2014-05-27 12:12:15 +00:00
2012-07-05 13:57:45 +00:00
## List users
2019-06-19 20:27:34 +00:00
Active users = Total accounts - Blocked users
2012-07-05 13:57:45 +00:00
Get a list of users.
2014-04-24 22:48:22 +00:00
2013-04-16 06:26:01 +00:00
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
2012-07-05 13:57:45 +00:00
2014-06-25 07:18:52 +00:00
### For normal users
2014-06-13 15:02:42 +00:00
```
GET /users
```
```json
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/john_smith"
2014-06-13 15:02:42 +00:00
},
{
"id": 2,
"username": "jack_smith",
"name": "Jack Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/jack_smith"
2014-06-13 15:02:42 +00:00
}
]
```
2019-04-28 23:49:25 +00:00
You can also search for users by name or primary email using `?search=` . For example. `/users?search=John` .
2018-07-16 12:49:46 +00:00
In addition, you can lookup users by username:
```
GET /users?username=:username
```
For example:
```
GET /users?username=jack_smith
```
2016-10-25 21:08:53 +00:00
In addition, you can filter users based on states eg. `blocked` , `active`
This works only to filter users who are `blocked` or `active` .
It does not support `active=false` or `blocked=false` .
```
GET /users?active=true
```
```
GET /users?blocked=true
```
2018-10-18 09:06:44 +00:00
NOTE: **Note:**
Username search is case insensitive.
2014-06-25 07:18:52 +00:00
### For admins
2014-06-13 15:02:42 +00:00
2012-07-05 13:57:45 +00:00
```
GET /users
```
2019-07-04 08:22:41 +00:00
| 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 |
2018-02-06 13:37:52 +00:00
2012-07-05 13:57:45 +00:00
```json
[
{
"id": 1,
2012-12-10 22:46:31 +00:00
"username": "john_smith",
2012-07-05 13:57:45 +00:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 23:41:15 +00:00
"state": "active",
2016-05-01 20:48:26 +00:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 13:57:45 +00:00
"created_at": "2012-05-23T08:00:58Z",
2017-06-20 14:54:29 +00:00
"is_admin": false,
2012-07-05 13:57:45 +00:00
"bio": null,
2016-05-01 20:48:26 +00:00
"location": null,
2012-07-05 13:57:45 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 19:07:00 +00:00
"website_url": "",
2016-09-26 17:33:00 +00:00
"organization": "",
2016-05-01 20:48:26 +00:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-09-11 15:44:42 +00:00
"theme_id": 1,
2017-03-27 13:43:10 +00:00
"last_activity_on": "2012-05-23",
2013-07-31 10:52:23 +00:00
"color_scheme_id": 2,
2016-05-01 20:48:26 +00:00
"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"}
],
2015-02-09 12:52:42 +00:00
"can_create_group": true,
2016-05-01 20:48:26 +00:00
"can_create_project": true,
"two_factor_enabled": true,
2018-07-24 12:46:19 +00:00
"external": false,
2020-01-24 00:08:51 +00:00
"private_profile": false,
"current_sign_in_ip": "196.165.1.102",
"last_sign_in_ip": "172.127.2.22"
2012-07-05 13:57:45 +00:00
},
{
"id": 2,
2012-12-10 22:46:31 +00:00
"username": "jack_smith",
2012-07-05 13:57:45 +00:00
"email": "jack@example.com",
"name": "Jack Smith",
2013-05-28 23:41:15 +00:00
"state": "blocked",
2016-05-01 20:48:26 +00:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/jack_smith",
2012-07-05 13:57:45 +00:00
"created_at": "2012-05-23T08:01:01Z",
2017-06-20 14:54:29 +00:00
"is_admin": false,
2012-07-05 13:57:45 +00:00
"bio": null,
2016-04-05 23:57:21 +00:00
"location": null,
2012-07-05 13:57:45 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 19:07:00 +00:00
"website_url": "",
2016-09-26 17:33:00 +00:00
"organization": "",
2016-05-01 20:48:26 +00:00
"last_sign_in_at": null,
"confirmed_at": "2012-05-30T16:53:06.148Z",
2017-09-11 15:44:42 +00:00
"theme_id": 1,
2017-03-27 13:43:10 +00:00
"last_activity_on": "2012-05-23",
2013-07-31 10:52:23 +00:00
"color_scheme_id": 3,
2015-02-09 12:52:42 +00:00
"projects_limit": 100,
2015-06-24 05:36:35 +00:00
"current_sign_in_at": "2014-03-19T17:54:13Z",
2016-05-01 20:48:26 +00:00
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": true,
2018-07-24 12:46:19 +00:00
"external": false,
2020-01-24 00:08:51 +00:00
"private_profile": false,
"current_sign_in_ip": "10.165.1.102",
"last_sign_in_ip": "172.127.2.22"
2012-07-05 13:57:45 +00:00
}
]
```
2019-07-16 09:22:40 +00:00
Users on GitLab [Starter, Bronze, or higher ](https://about.gitlab.com/pricing/ ) will also see the `shared_runners_minutes_limit` , `extra_shared_runners_minutes_limit` , and `note` parameters.
```json
[
{
"id": 1,
...
"shared_runners_minutes_limit": 133,
"extra_shared_runners_minutes_limit": 133,
"note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
...
}
]
```
2019-07-03 10:27:06 +00:00
Users on GitLab [Silver or higher ](https://about.gitlab.com/pricing/ ) will also see
the `group_saml` provider option:
```json
[
{
"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}
],
...
}
]
2019-07-09 07:16:55 +00:00
```
2019-07-03 10:27:06 +00:00
2018-07-16 12:49:46 +00:00
You can lookup users by external UID and provider:
2017-02-16 01:44:36 +00:00
```
GET /users?extern_uid=:extern_uid& provider=:provider
```
For example:
```
GET /users?extern_uid=1234567& provider=github
```
2016-10-25 21:08:53 +00:00
You can search for users who are external with: `/users?external=true`
2017-07-07 07:56:47 +00:00
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
```
2017-09-28 16:49:42 +00:00
You can filter by [custom attributes ](custom_attributes.md ) with:
```
GET /users?custom_attributes[key]=value& custom_attributes[other_key]=other_value
```
2017-12-22 15:54:55 +00:00
You can include the users' [custom attributes ](custom_attributes.md ) in the response with:
```
GET /users?with_custom_attributes=true
```
2012-07-05 13:57:45 +00:00
## Single user
Get a single user.
2014-06-25 07:18:52 +00:00
### For user
2014-06-13 15:02:42 +00:00
```
GET /users/:id
```
Parameters:
- `id` (required) - The ID of a user
```json
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/john_smith",
2015-12-28 14:50:44 +00:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-04-05 23:57:21 +00:00
"location": null,
2018-09-25 16:40:24 +00:00
"public_email": "john@example.com",
2015-12-28 14:50:44 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
2016-09-26 17:33:00 +00:00
"website_url": "",
"organization": ""
2014-06-13 15:02:42 +00:00
}
```
2014-06-25 07:18:52 +00:00
### For admin
2014-06-13 15:02:42 +00:00
2012-07-05 13:57:45 +00:00
```
GET /users/:id
```
Parameters:
2014-04-24 22:48:22 +00:00
- `id` (required) - The ID of a user
2012-07-05 13:57:45 +00:00
2019-07-03 09:32:54 +00:00
Example Responses:
2012-07-05 13:57:45 +00:00
```json
{
"id": 1,
2012-12-10 22:46:31 +00:00
"username": "john_smith",
2012-07-05 13:57:45 +00:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 23:41:15 +00:00
"state": "active",
2016-05-01 20:48:26 +00:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 13:57:45 +00:00
"created_at": "2012-05-23T08:00:58Z",
2017-06-20 14:54:29 +00:00
"is_admin": false,
2012-07-05 13:57:45 +00:00
"bio": null,
2016-04-05 23:57:21 +00:00
"location": null,
2018-09-25 16:40:24 +00:00
"public_email": "john@example.com",
2012-07-05 13:57:45 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 19:07:00 +00:00
"website_url": "",
2016-09-26 17:33:00 +00:00
"organization": "",
2016-05-01 20:48:26 +00:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-09-11 15:44:42 +00:00
"theme_id": 1,
2017-03-27 13:43:10 +00:00
"last_activity_on": "2012-05-23",
2013-07-31 10:52:23 +00:00
"color_scheme_id": 2,
2016-05-01 20:48:26 +00:00
"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"}
],
2013-10-01 11:52:57 +00:00
"can_create_group": true,
2014-11-01 23:14:42 +00:00
"can_create_project": true,
2016-05-01 20:48:26 +00:00
"two_factor_enabled": true,
2018-07-24 12:46:19 +00:00
"external": false,
2020-01-24 00:08:51 +00:00
"private_profile": false,
"current_sign_in_ip": "196.165.1.102",
"last_sign_in_ip": "172.127.2.22"
2012-07-05 13:57:45 +00:00
}
```
2019-07-03 09:32:54 +00:00
Users on GitLab [Starter, Bronze, or higher ](https://about.gitlab.com/pricing/ ) will also see
2019-07-16 09:22:40 +00:00
the `shared_runners_minutes_limit` , `extra_shared_runners_minutes_limit` , and `note` parameters.
2019-07-04 08:22:41 +00:00
```json
{
"id": 1,
"username": "john_smith",
"shared_runners_minutes_limit": 133,
2019-07-16 09:22:40 +00:00
"extra_shared_runners_minutes_limit": 133,
"note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
2019-07-04 08:22:41 +00:00
...
}
```
Users on GitLab.com [Silver, or higher ](https://about.gitlab.com/pricing/ ) will also
see the `group_saml` option:
2019-07-03 09:32:54 +00:00
```json
{
"id": 1,
"username": "john_smith",
"shared_runners_minutes_limit": 133,
2019-07-16 09:22:40 +00:00
"extra_shared_runners_minutes_limit": 133,
"note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
2019-07-03 10:27:06 +00:00
"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}
],
2019-07-03 09:32:54 +00:00
...
}
```
2017-12-22 15:54:55 +00:00
You can include the user's [custom attributes ](custom_attributes.md ) in the response with:
```
GET /users/:id?with_custom_attributes=true
```
2012-10-02 09:52:13 +00:00
## User creation
2013-02-20 11:10:51 +00:00
2019-06-27 19:41:51 +00:00
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.
Note that `force_random_password` and `reset_password` take priority
over `password` . In addition, `reset_password` and
`force_random_password` can be used together.
2012-10-02 09:52:13 +00:00
2019-07-19 09:53:19 +00:00
NOTE: **Note:**
2020-02-06 15:09:11 +00:00
From [GitLab 12.1 ](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/ ), `private_profile` will default to `false` .
2019-07-19 09:53:19 +00:00
2012-10-02 09:52:13 +00:00
```
POST /users
```
Parameters:
2019-07-03 09:32:54 +00:00
- `email` (required) - Email
- `password` (optional) - Password
- `reset_password` (optional) - Send user password reset link - true or false(default)
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
- `linkedin` (optional) - LinkedIn
- `twitter` (optional) - Twitter account
- `website_url` (optional) - Website URL
- `organization` (optional) - Organization name
- `projects_limit` (optional) - Number of projects user can create
- `extern_uid` (optional) - External UID
- `provider` (optional) - External provider name
- `bio` (optional) - User's biography
- `location` (optional) - User's location
- `public_email` (optional) - The public email of the user
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
- `skip_confirmation` (optional) - Skip confirmation - true or false (default)
2019-07-15 21:07:54 +00:00
- `external` (optional) - Flags the user as external - true or false (default)
2019-07-03 09:32:54 +00:00
- `avatar` (optional) - Image file for user's avatar
2020-02-07 00:09:12 +00:00
- `theme_id` (optional) - The GitLab theme for the user (see [the user preference docs ](../user/profile/preferences.md#navigation-theme ) for more information)
- `color_scheme_id` (optional) - User's color scheme for the file viewer (see [the user preference docs ](../user/profile/preferences.md#syntax-highlighting-theme ) for more information)
2020-02-06 21:08:48 +00:00
- `private_profile` (optional) - User's profile is private - true, false (default), or null (will be converted to false)
2019-07-08 08:50:38 +00:00
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user ** (STARTER)**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user ** (STARTER)**
2012-10-02 09:52:13 +00:00
2012-12-18 19:24:31 +00:00
## User modification
2013-02-20 11:10:51 +00:00
Modifies an existing user. Only administrators can change attributes of a user.
2012-12-18 19:24:31 +00:00
```
PUT /users/:id
```
Parameters:
2013-02-20 11:10:51 +00:00
2019-09-19 09:06:27 +00:00
- `id` (required) - The ID of the user
- `email` (optional) - Email
- `username` (optional) - Username
- `name` (optional) - Name
- `password` (optional) - Password
- `skype` (optional) - Skype ID
- `linkedin` (optional) - LinkedIn
- `twitter` (optional) - Twitter account
- `website_url` (optional) - Website URL
- `organization` (optional) - Organization name
- `projects_limit` (optional) - Limit projects each user can create
- `extern_uid` (optional) - External UID
- `provider` (optional) - External provider name
2019-06-19 20:27:34 +00:00
- `group_id_for_saml` (optional) - ID of group where SAML has been configured
2019-09-19 09:06:27 +00:00
- `bio` (optional) - User's biography
2018-09-26 15:27:26 +00:00
- `location` (optional) - User's location
- `public_email` (optional) - The public email of the user
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
2017-11-21 15:47:58 +00:00
- `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)
2019-07-15 21:07:54 +00:00
- `external` (optional) - Flags the user as external - true or false (default)
2019-06-19 20:27:34 +00:00
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
2018-09-26 15:27:26 +00:00
- `avatar` (optional) - Image file for user's avatar
2020-02-07 00:09:12 +00:00
- `theme_id` (optional) - The GitLab theme for the user (see [the user preference docs ](../user/profile/preferences.md#navigation-theme ) for more information)
- `color_scheme_id` (optional) - User's color scheme for the file viewer (see [the user preference docs ](../user/profile/preferences.md#syntax-highlighting-theme ) for more information)
2020-02-06 21:08:48 +00:00
- `private_profile` (optional) - User's profile is private - true, false (default), or null (will be converted to false)
2019-07-08 08:50:38 +00:00
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user ** (STARTER)**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user ** (STARTER)**
2019-09-19 09:06:27 +00:00
- `note` (optional) - Admin notes for this user ** (STARTER)**
2014-06-25 07:18:52 +00:00
2017-02-02 15:15:02 +00:00
On password update, user will be forced to change it upon next login.
2016-11-24 17:28:52 +00:00
Note, at the moment this method does only return a `404` error,
even in cases where a `409` (Conflict) would be more appropriate,
2014-06-25 07:18:52 +00:00
e.g. when renaming the email address to some existing one.
2012-12-18 19:24:31 +00:00
## User deletion
2013-02-20 11:10:51 +00:00
2014-06-25 07:18:52 +00:00
Deletes a user. Available only for administrators.
2019-12-12 00:07:43 +00:00
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.
2012-12-18 19:24:31 +00:00
```
DELETE /users/:id
```
2013-02-20 11:10:51 +00:00
Parameters:
2014-04-24 22:48:22 +00:00
- `id` (required) - The ID of the user
2017-06-01 16:14:39 +00:00
- `hard_delete` (optional) - If true, contributions that would usually be
[moved to the ghost user ](../user/profile/account/delete_account.md#associated-records )
will be deleted instead, as well as groups owned solely by this user.
2012-12-18 19:24:31 +00:00
2019-07-04 08:22:41 +00:00
## List current user (for normal users)
2012-07-05 13:57:45 +00:00
2013-02-20 11:10:51 +00:00
Gets currently authenticated user.
2012-07-05 13:57:45 +00:00
```
GET /user
```
```json
{
"id": 1,
2012-12-10 22:46:31 +00:00
"username": "john_smith",
2012-07-05 13:57:45 +00:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 23:41:15 +00:00
"state": "active",
2016-05-01 20:48:26 +00:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 11:24:09 +00:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 13:57:45 +00:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-04-05 23:57:21 +00:00
"location": null,
2018-09-25 16:40:24 +00:00
"public_email": "john@example.com",
2012-07-05 13:57:45 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 19:07:00 +00:00
"website_url": "",
2016-09-26 17:33:00 +00:00
"organization": "",
2016-05-01 20:48:26 +00:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-09-11 15:44:42 +00:00
"theme_id": 1,
2017-03-27 13:43:10 +00:00
"last_activity_on": "2012-05-23",
2013-08-30 19:04:26 +00:00
"color_scheme_id": 2,
2016-05-01 20:48:26 +00:00
"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"}
],
2014-04-05 06:36:47 +00:00
"can_create_group": true,
2014-11-01 23:14:42 +00:00
"can_create_project": true,
2016-05-01 20:48:26 +00:00
"two_factor_enabled": true,
2018-07-24 12:46:19 +00:00
"external": false,
"private_profile": false
2012-07-05 13:57:45 +00:00
}
```
2012-09-21 11:49:28 +00:00
2019-07-04 08:22:41 +00:00
## List current user (for admins)
2016-11-21 12:59:37 +00:00
Parameters:
2017-07-12 10:18:14 +00:00
- `sudo` (optional) - the ID of a user to make the call in their place
2016-11-21 12:59:37 +00:00
```
GET /user
```
```json
{
"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": null,
"location": null,
2018-09-25 16:40:24 +00:00
"public_email": "john@example.com",
2016-11-21 12:59:37 +00:00
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-09-11 15:44:42 +00:00
"theme_id": 1,
2017-03-27 13:43:10 +00:00
"last_activity_on": "2012-05-23",
2016-11-21 12:59:37 +00:00
"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,
2018-07-24 12:46:19 +00:00
"external": false,
2020-01-24 00:08:51 +00:00
"private_profile": false,
"current_sign_in_ip": "196.165.1.102",
"last_sign_in_ip": "172.127.2.22"
2016-11-21 12:59:37 +00:00
}
```
2018-07-13 15:52:31 +00:00
## User status
Get the status of the currently signed in user.
```
GET /user/status
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/user/status"
2018-07-26 15:14:02 +00:00
```
Example response:
2018-07-13 15:52:31 +00:00
```json
{
"emoji":"coffee",
2018-07-26 15:14:02 +00:00
"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 > "
2018-07-13 15:52:31 +00:00
}
```
## Get the status of a user
Get the status of a user.
```
GET /users/:id_or_username/status
```
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `id_or_username` | string | yes | The id or username of the user to get a status of |
2018-07-26 15:14:02 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-07-26 15:14:02 +00:00
curl "https://gitlab.example.com/users/janedoe/status"
```
Example response:
2018-07-13 15:52:31 +00:00
```json
{
"emoji":"coffee",
2018-07-26 15:14:02 +00:00
"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 > "
2018-07-13 15:52:31 +00:00
}
```
## Set user status
Set the status of the current user.
```
PUT /user/status
```
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
2019-10-07 18:06:24 +00:00
| `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 [Gemojione index ](https://github.com/bonusly/gemojione/blob/master/config/index.json ). |
2018-07-26 09:48:58 +00:00
| `message` | string | no | The message to set as a status. It can also contain emoji codes. |
2018-07-13 15:52:31 +00:00
2018-07-26 15:14:02 +00:00
When both parameters `emoji` and `message` are empty, the status will be cleared.
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " --data "emoji=coffee" --data "message=I crave coffee" https://gitlab.example.com/api/v4/user/status
2018-07-26 15:14:02 +00:00
```
Example responses
```json
{
"emoji":"coffee",
"message":"I crave coffee",
"message_html": "I crave coffee"
}
```
2018-07-13 15:52:31 +00:00
2019-07-09 08:44:19 +00:00
## User counts
2019-07-12 08:15:38 +00:00
Get the counts (same as in top right menu) of the currently signed in user.
2019-07-09 08:44:19 +00:00
| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `merge_requests` | number | Merge requests that are active and assigned to current user. |
```
GET /user_counts
```
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 08:44:19 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/user_counts"
```
Example response:
```json
{
"merge_requests": 4
}
```
2018-01-12 13:46:20 +00:00
## List user projects
2019-07-04 08:22:41 +00:00
Please refer to the [List of user projects ](projects.md#list-user-projects ).
2018-01-12 13:46:20 +00:00
2012-09-21 11:49:28 +00:00
## List SSH keys
Get a list of currently authenticated user's SSH keys.
```
GET /user/keys
```
```json
[
{
"id": 1,
2014-04-05 06:36:47 +00:00
"title": "Public key",
2014-11-18 12:59:04 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 11:49:28 +00:00
},
{
"id": 3,
2014-04-05 06:36:47 +00:00
"title": "Another Public key",
2014-11-18 12:59:04 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 11:49:28 +00:00
}
]
```
2013-02-20 11:10:51 +00:00
Parameters:
2014-04-24 22:48:22 +00:00
- **none**
2013-02-20 11:10:51 +00:00
2014-04-15 14:39:46 +00:00
## List SSH keys for user
2018-06-28 06:13:21 +00:00
Get a list of a specified user's SSH keys.
2014-04-15 14:39:46 +00:00
```
2020-01-20 09:08:32 +00:00
GET /users/:id_or_username/keys
2014-04-15 14:39:46 +00:00
```
2020-01-20 09:08:32 +00:00
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `id_or_username` | string | yes | The id or username of the user to get the SSH keys for. |
2013-02-20 11:10:51 +00:00
2012-09-21 11:49:28 +00:00
## Single SSH key
Get a single key.
```
2016-10-27 08:20:06 +00:00
GET /user/keys/:key_id
2012-09-21 11:49:28 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `key_id` (required) - The ID of an SSH key
2012-09-21 11:49:28 +00:00
```json
{
"id": 1,
2014-04-05 06:36:47 +00:00
"title": "Public key",
2014-11-18 12:59:04 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 11:49:28 +00:00
}
```
2013-02-20 11:10:51 +00:00
2012-09-21 11:49:28 +00:00
## Add SSH key
2013-02-20 11:10:51 +00:00
Creates a new key owned by the currently authenticated user.
2012-09-21 11:49:28 +00:00
```
POST /user/keys
```
Parameters:
2014-04-24 22:48:22 +00:00
- `title` (required) - new SSH Key's title
2014-06-25 07:18:52 +00:00
- `key` (required) - new SSH key
2012-09-21 11:49:28 +00:00
2015-01-21 17:57:54 +00:00
```json
{
"created_at": "2015-01-21T17:44:33.512Z",
"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",
"title": "ABC",
"id": 4
}
```
2015-01-21 18:08:15 +00:00
Will return created key with status `201 Created` on success. If an
error occurs a `400 Bad Request` is returned with a message explaining the error:
```json
{
"message": {
"fingerprint": [
"has already been taken"
],
"key": [
"has already been taken"
]
}
}
```
2013-03-06 04:48:40 +00:00
## Add SSH key for user
Create new key owned by specified user. Available only for admin
```
POST /users/:id/keys
```
Parameters:
2014-06-25 07:18:52 +00:00
- `id` (required) - id of specified user
2014-04-24 22:48:22 +00:00
- `title` (required) - new SSH Key's title
2014-06-25 07:18:52 +00:00
- `key` (required) - new SSH key
2013-03-06 04:48:40 +00:00
2014-04-24 22:48:22 +00:00
## Delete SSH key for current user
2012-09-21 11:49:28 +00:00
2014-06-25 07:18:52 +00:00
Deletes key owned by currently authenticated user.
2017-09-06 07:15:34 +00:00
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
2012-09-21 11:49:28 +00:00
```
2016-10-27 08:20:06 +00:00
DELETE /user/keys/:key_id
2012-09-21 11:49:28 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `key_id` (required) - SSH key ID
2012-09-21 11:49:28 +00:00
2014-04-24 22:48:22 +00:00
## Delete SSH key for given user
2014-04-15 14:39:46 +00:00
Deletes key owned by a specified user. Available only for admin.
```
2016-10-27 08:20:06 +00:00
DELETE /users/:id/keys/:key_id
2014-04-15 14:39:46 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
- `key_id` (required) - SSH key ID
2014-04-15 14:39:46 +00:00
2017-09-05 09:32:27 +00:00
## List all GPG keys
Get a list of currently authenticated user's GPG keys.
```
GET /user/gpg_keys
```
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/user/gpg_keys
2017-09-05 09:32:27 +00:00
```
Example response:
```json
[
{
"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:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `key_id` | integer | yes | The ID of the GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/user/gpg_keys/1
2017-09-05 09:32:27 +00:00
```
Example response:
```json
{
"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:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| key | string | yes | The new GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
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
2017-09-05 09:32:27 +00:00
```
Example response:
```json
[
{
"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:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `key_id` | integer | yes | The ID of the GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/user/gpg_keys/1
2017-09-05 09:32:27 +00:00
```
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. Available only for admins.
```
GET /users/:id/gpg_keys
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/2/gpg_keys
2017-09-05 09:32:27 +00:00
```
Example response:
```json
[
{
"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. Available only for admins.
```
GET /users/:id/gpg_keys/:key_id
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/2/gpg_keys/1
2017-09-05 09:32:27 +00:00
```
Example response:
```json
{
"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 admins.
```
POST /users/:id/gpg_keys
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
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
2017-09-05 09:32:27 +00:00
```
Example response:
```json
[
{
"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 admins.
```
DELETE /users/:id/gpg_keys/:key_id
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/2/gpg_keys/1
2017-09-05 09:32:27 +00:00
```
2015-07-29 13:40:08 +00:00
## List emails
Get a list of currently authenticated user's emails.
```
GET /user/emails
```
```json
[
{
"id": 1,
"email": "email@example.com"
},
{
"id": 3,
"email": "email2@example.com"
}
]
```
Parameters:
- **none**
## List emails for user
Get a list of a specified user's emails. Available only for admin
```
2016-10-27 08:20:06 +00:00
GET /users/:id/emails
2015-07-29 13:40:08 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
2015-07-29 13:40:08 +00:00
2015-07-30 09:41:59 +00:00
## Single email
2015-07-29 13:40:08 +00:00
2015-07-30 09:41:59 +00:00
Get a single email.
2015-07-29 13:40:08 +00:00
```
2016-10-27 08:20:06 +00:00
GET /user/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `email_id` (required) - email ID
2015-07-29 13:40:08 +00:00
```json
{
"id": 1,
"email": "email@example.com"
}
```
## Add email
Creates a new email owned by the currently authenticated user.
```
POST /user/emails
```
Parameters:
- `email` (required) - email address
```json
{
"id": 4,
"email": "email@example.com"
}
```
2015-07-30 09:41:59 +00:00
Will return created email with status `201 Created` on success. If an
2015-07-29 13:40:08 +00:00
error occurs a `400 Bad Request` is returned with a message explaining the error:
```json
{
"message": {
"email": [
"has already been taken"
]
}
}
```
## Add email for user
Create new email owned by specified user. Available only for admin
```
POST /users/:id/emails
```
Parameters:
- `id` (required) - id of specified user
- `email` (required) - email address
2018-09-09 21:04:11 +00:00
- `skip_confirmation` (optional) - Skip confirmation and assume e-mail is verified - true or false (default)
2015-07-29 13:40:08 +00:00
## Delete email for current user
Deletes email owned by currently authenticated user.
2017-09-06 07:15:34 +00:00
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
2015-07-29 13:40:08 +00:00
```
2016-10-27 08:20:06 +00:00
DELETE /user/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `email_id` (required) - email ID
2015-07-29 13:40:08 +00:00
## Delete email for given user
Deletes email owned by a specified user. Available only for admin.
```
2016-10-27 08:20:06 +00:00
DELETE /users/:id/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
- `email_id` (required) - email ID
2015-07-29 13:40:08 +00:00
2015-04-28 16:02:44 +00:00
## Block user
2019-11-12 00:06:21 +00:00
Blocks the specified user. Available only for admin.
2015-04-28 16:02:44 +00:00
```
2017-02-20 12:31:11 +00:00
POST /users/:id/block
2015-04-28 16:02:44 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
2015-04-28 16:02:44 +00:00
2017-02-20 12:31:11 +00:00
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
2015-12-30 18:52:02 +00:00
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
2015-04-28 16:02:44 +00:00
## Unblock user
2019-11-12 00:06:21 +00:00
Unblocks the specified user. Available only for admin.
2015-04-28 16:02:44 +00:00
```
2017-02-20 12:31:11 +00:00
POST /users/:id/unblock
2015-04-28 16:02:44 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
2015-04-28 16:02:44 +00:00
2017-02-20 12:31:11 +00:00
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
2015-12-30 18:52:02 +00:00
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
2016-10-10 11:35:26 +00:00
2019-10-10 00:06:44 +00:00
## Deactivate user
2020-02-10 00:09:07 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22257) in GitLab 12.4.
2019-10-10 00:06:44 +00:00
Deactivates the specified user. Available only for admin.
```
POST /users/:id/deactivate
```
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 deactivate a user:
- Blocked by admin or by LDAP synchronization.
2019-10-23 00:06:29 +00:00
- That has any activity in past 180 days. These users cannot be deactivated.
2019-10-10 00:06:44 +00:00
## Activate user
2020-02-10 00:09:07 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22257) in GitLab 12.4.
2019-10-10 00:06:44 +00:00
Activates the specified user. Available only for admin.
```
POST /users/:id/activate
```
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 activate a user blocked by admin or by LDAP synchronization.
2016-10-10 11:35:26 +00:00
### Get user contribution events
2017-05-29 05:49:17 +00:00
Please refer to the [Events API documentation ](events.md#get-user-contribution-events )
2016-10-10 11:35:26 +00:00
2017-03-17 14:23:52 +00:00
## Get all impersonation tokens of a user
2017-01-04 10:51:17 +00:00
2017-03-17 14:23:52 +00:00
> Requires admin permissions.
It retrieves every impersonation token of the user. Use the pagination
parameters `page` and `per_page` to restrict the list of impersonation tokens.
2017-01-04 10:51:17 +00:00
```
2017-03-01 16:59:03 +00:00
GET /users/:user_id/impersonation_tokens
2017-01-04 10:51:17 +00:00
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------------------------------------- |
| `user_id` | integer | yes | The ID of the user |
| `state` | string | no | filter tokens based on state (`all`, `active` , `inactive` ) |
2017-03-17 14:23:52 +00:00
```
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/42/impersonation_tokens
2017-03-17 14:23:52 +00:00
```
2017-01-04 10:51:17 +00:00
2017-02-27 18:56:54 +00:00
Example response:
2017-03-17 14:23:52 +00:00
2017-01-04 10:51:17 +00:00
```json
[
2017-03-17 14:23:52 +00:00
{
"active" : true,
"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,
"scopes" : [
"read_user"
],
"revoked" : true,
"name" : "mytoken2",
"created_at" : "2017-03-17T17:19:28.697Z",
"id" : 3,
"impersonation" : true,
"expires_at" : "2017-04-14"
}
2017-01-04 10:51:17 +00:00
]
```
2017-03-17 14:23:52 +00:00
## Get an impersonation token of a user
2017-02-09 15:21:09 +00:00
2017-03-17 14:23:52 +00:00
> Requires admin permissions.
It shows a user's impersonation token.
2017-02-09 15:21:09 +00:00
```
2017-03-01 16:59:03 +00:00
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
2017-02-09 15:21:09 +00:00
```
Parameters:
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| ------------------------ | ------- | -------- | --------------------------------- |
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
2017-02-09 15:21:09 +00:00
2017-03-17 14:23:52 +00:00
```
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
2017-03-17 14:23:52 +00:00
```
Example response:
```json
{
"active" : true,
"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 admin permissions.
2018-11-08 15:03:56 +00:00
> Token values are returned once. Make sure you save it - you won't be able to access it again.
2017-03-01 16:59:03 +00:00
It creates a new impersonation token. Note that only administrators can do this.
2017-02-09 15:21:09 +00:00
You are only able to create impersonation tokens to impersonate the user and perform
2017-06-13 12:10:31 +00:00
both API calls and Git reads and writes. The user will not see these tokens in their profile
2017-02-09 15:21:09 +00:00
settings page.
2017-01-04 10:51:17 +00:00
```
2017-03-01 16:59:03 +00:00
POST /users/:user_id/impersonation_tokens
2017-01-04 10:51:17 +00:00
```
2019-07-04 08:22:41 +00:00
| Attribute | Type | Required | Description |
| ------------ | ------- | -------- | ----------- |
| `user_id` | integer | yes | The ID of the user |
| `name` | string | yes | The name of the impersonation token |
| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user` ) |
2017-03-17 14:23:52 +00:00
```
2018-12-27 09:03:08 +00:00
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
2017-03-17 14:23:52 +00:00
```
2017-01-04 10:51:17 +00:00
2017-03-01 16:59:03 +00:00
Example response:
2017-03-17 14:23:52 +00:00
2017-03-01 16:59:03 +00:00
```json
{
2017-03-17 14:23:52 +00:00
"id" : 2,
"revoked" : false,
"scopes" : [
"api"
],
"token" : "EsMo-vhKfXGwX9RKrwiy",
"active" : true,
"impersonation" : true,
"name" : "mytoken",
"created_at" : "2017-03-17T17:18:09.283Z",
"expires_at" : "2017-04-04"
2017-03-01 16:59:03 +00:00
}
```
2017-01-04 10:51:17 +00:00
2017-03-01 16:59:03 +00:00
## Revoke an impersonation token
2017-03-17 14:23:52 +00:00
> Requires admin permissions.
It revokes an impersonation token.
2017-01-04 10:51:17 +00:00
```
2017-03-01 16:59:03 +00:00
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
2017-01-04 10:51:17 +00:00
```
2017-03-17 14:23:52 +00:00
```
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
2017-03-17 14:23:52 +00:00
```
2017-01-04 10:51:17 +00:00
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-03-01 16:59:03 +00:00
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
2017-04-12 11:19:45 +00:00
### Get user activities (admin only)
2019-07-04 08:22:41 +00:00
NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
2017-04-12 11:19:45 +00:00
Get the last activity date for all users, sorted from oldest to newest.
The activities that update the timestamp are:
2019-07-04 08:22:41 +00:00
- Git HTTP/SSH activities (such as clone, push)
- User logging in into GitLab
2019-09-18 14:02:45 +00:00
- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/54947) in GitLab 11.8)
2017-04-12 11:19:45 +00:00
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:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` . Defaults to 6 months ago. |
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/user/activities
2017-04-12 11:19:45 +00:00
```
Example response:
```json
[
{
"username": "user1",
2017-03-27 13:43:10 +00:00
"last_activity_on": "2015-12-14",
"last_activity_at": "2015-12-14"
2017-04-12 11:19:45 +00:00
},
{
"username": "user2",
2017-03-27 13:43:10 +00:00
"last_activity_on": "2015-12-15",
"last_activity_at": "2015-12-15"
2017-04-12 11:19:45 +00:00
},
{
"username": "user3",
2017-03-27 13:43:10 +00:00
"last_activity_on": "2015-12-16",
"last_activity_at": "2015-12-16"
2017-04-12 11:19:45 +00:00
}
]
2017-03-27 13:43:10 +00:00
```
Please note that `last_activity_at` is deprecated, please use `last_activity_on` .
2020-01-22 15:08:48 +00:00
## User memberships (admin only)
2020-02-06 15:09:11 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22518) in GitLab 12.8.
2020-01-22 15:08:48 +00:00
Lists all projects and groups a user is a member of. This endpoint is available for admins only.
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, will not be included.
Access levels will be represented by an integer value. Read more about the meaning of access level values [here ](access_requests.md#valid-access-levels ).
```
GET /users/:id/memberships
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The 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 cannot be found.
- `403 Forbidden` when not requested by an admin.
- `400 Bad Request` when requested type is not supported.
2020-01-30 15:09:15 +00:00
```shell
2020-01-22 15:08:48 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/users/< user_id > /memberships
```
Example response:
```json
[
{
"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"
},
]
```