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,
"private_profile": false
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,
2019-05-30 06:10:52 +00:00
"private_profile": false
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,
2019-07-03 10:27:06 +00:00
"private_profile": false
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:**
2019-09-18 14:02:45 +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
2019-07-15 21:07:54 +00:00
- `private_profile` (optional) - User's profile is private - true or false (default)
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
2019-07-15 21:07:54 +00:00
- `private_profile` (optional) - User's profile is private - true or false (default)
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.
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-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,
"private_profile": false
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
```
2018-07-26 15:14:02 +00:00
```bash
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
```bash
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.
```bash
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
```
```bash
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
```
2016-10-27 08:20:06 +00:00
GET /users/:id/keys
2014-04-15 14:39:46 +00:00
```
Parameters:
2016-10-27 08:20:06 +00:00
- `id` (required) - id of specified user
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
```
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
Blocks the specified user. Available only for admin.
```
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
Unblocks the specified user. Available only for admin.
```
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
### 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. |
```bash
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` .