2020-10-28 15:08:49 +00:00
---
2021-02-08 18:09:49 +00:00
stage: Manage
2022-01-27 03:14:06 +00:00
group: Authentication and Authorization
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-28 15:08:49 +00:00
---
2021-09-07 03:11:39 +00:00
# Users API **(FREE)**
2014-05-27 12:12:15 +00:00
2012-07-05 13:57:45 +00:00
## List users
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
2020-02-29 03:07:51 +00:00
```plaintext
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
}
]
```
2022-02-04 00:13:53 +00:00
You can also search for users by name, username or public email by using `?search=` . For example. `/users?search=John` .
2018-07-16 12:49:46 +00:00
In addition, you can lookup users by username:
2020-02-29 03:07:51 +00:00
```plaintext
2018-07-16 12:49:46 +00:00
GET /users?username=:username
```
For example:
2020-02-29 03:07:51 +00:00
```plaintext
2018-07-16 12:49:46 +00:00
GET /users?username=jack_smith
```
2021-02-24 15:11:10 +00:00
NOTE:
Username search is case insensitive.
2020-09-16 18:09:47 +00:00
In addition, you can filter users based on the states `blocked` and `active` .
2020-11-23 18:09:14 +00:00
It does not support `active=false` or `blocked=false` . The list of billable users
2020-09-16 18:09:47 +00:00
is the total number of users minus the blocked users.
2016-10-25 21:08:53 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-25 21:08:53 +00:00
GET /users?active=true
```
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-25 21:08:53 +00:00
GET /users?blocked=true
```
2021-02-24 15:11:10 +00:00
In addition, you can search for external users only with `external=true` .
It does not support `external=false` .
```plaintext
GET /users?external=true
```
2021-02-04 00:09:18 +00:00
GitLab supports bot users such as the [alert bot ](../operations/incident_management/integrations.md )
2020-08-31 15:10:41 +00:00
or the [support bot ](../user/project/service_desk.md#support-bot-user ).
2021-02-24 15:11:10 +00:00
You can exclude the following types of [internal users ](../development/internal_users.md#internal-users )
2022-02-10 09:16:20 +00:00
from the users' list with the `exclude_internal=true` parameter
([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4):
2020-08-31 15:10:41 +00:00
2021-02-24 15:11:10 +00:00
- Alert bot
- Support bot
2022-01-21 06:16:15 +00:00
However, this action does not exclude [bot users for projects ](../user/project/settings/project_access_tokens.md#bot-users-for-projects )
or [bot users for groups ](../user/group/settings/group_access_tokens.md#bot-users-for-groups ).
2021-02-24 15:11:10 +00:00
2020-08-31 15:10:41 +00:00
```plaintext
GET /users?exclude_internal=true
```
2021-02-24 15:11:10 +00:00
In addition, to exclude external users from the users' list, you can use the parameter `exclude_external=true` .
```plaintext
GET /users?exclude_external=true
```
2018-10-18 09:06:44 +00:00
2022-03-31 00:08:33 +00:00
To exclude [bot users for projects ](../user/project/settings/project_access_tokens.md#bot-users-for-projects )
and [bot users for groups ](../user/group/settings/group_access_tokens.md#bot-users-for-groups ), you can use the
parameter `without_project_bots=true` .
```plaintext
GET /users?without_project_bots=true
```
2022-05-11 15:07:26 +00:00
### For administrators
2014-06-13 15:02:42 +00:00
2022-03-22 12:07:28 +00:00
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
2020-02-29 03:07:51 +00:00
```plaintext
2012-07-05 13:57:45 +00:00
GET /users
```
2020-06-04 00:08:17 +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 |
2021-02-08 15:09:38 +00:00
| `without_projects` | boolean | no | Filter users without projects. Default is `false` , which means that all users are returned, with and without projects. |
2022-02-02 15:17:50 +00:00
| `admins` | boolean | no | Return only administrators. Default is `false` |
2021-07-27 21:09:42 +00:00
| `saml_provider_id` ** (PREMIUM)** | number | no | Return only users created by the specified SAML provider ID. If not included, 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,
2020-07-13 12:09:18 +00:00
"bio": "",
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": "",
2020-03-03 09:07:54 +00:00
"job_title": "",
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",
2020-05-28 09:08:05 +00:00
"note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
2016-05-01 20:48:26 +00:00
"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",
2022-03-22 12:07:28 +00:00
"last_sign_in_ip": "172.127.2.22",
"namespace_id": 1
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,
2020-07-13 12:09:18 +00:00
"bio": "",
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": "",
2020-03-03 09:07:54 +00:00
"job_title": "",
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",
2022-03-22 12:07:28 +00:00
"last_sign_in_ip": "172.127.2.22",
"namespace_id": 2
2012-07-05 13:57:45 +00:00
}
]
```
2021-09-07 03:11:39 +00:00
Users on [GitLab Premium or higher ](https://about.gitlab.com/pricing/ ) also see the `shared_runners_minutes_limit` , `extra_shared_runners_minutes_limit` , `is_auditor` , and `using_license_seat` parameters.
2019-07-16 09:22:40 +00:00
```json
[
{
"id": 1,
...
"shared_runners_minutes_limit": 133,
"extra_shared_runners_minutes_limit": 133,
2021-05-10 09:10:28 +00:00
"is_auditor": false,
2020-12-01 00:09:28 +00:00
"using_license_seat": true
2019-07-16 09:22:40 +00:00
...
}
]
```
2021-09-07 03:11:39 +00:00
Users on [GitLab Premium or higher ](https://about.gitlab.com/pricing/ ) also see
2021-05-26 06:10:25 +00:00
the `group_saml` provider option and `provisioned_by_group_id` parameter:
2019-07-03 10:27:06 +00:00
```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}
],
2021-05-26 06:10:25 +00:00
"provisioned_by_group_id": 123789
2019-07-03 10:27:06 +00:00
...
}
]
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
2020-02-29 03:07:51 +00:00
```plaintext
2017-02-16 01:44:36 +00:00
GET /users?extern_uid=:extern_uid& provider=:provider
```
For example:
2020-02-29 03:07:51 +00:00
```plaintext
2017-02-16 01:44:36 +00:00
GET /users?extern_uid=1234567& provider=github
```
2017-07-07 07:56:47 +00:00
You can search users by creation date time range with:
2020-02-29 03:07:51 +00:00
```plaintext
2017-07-07 07:56:47 +00:00
GET /users?created_before=2001-01-02T00:00:00.060Z& created_after=1999-01-02T00:00:00.060
```
2020-04-15 09:09:46 +00:00
You can search for users without projects with: `/users?without_projects=true`
2017-09-28 16:49:42 +00:00
You can filter by [custom attributes ](custom_attributes.md ) with:
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-28 16:49:42 +00:00
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:
2020-02-29 03:07:51 +00:00
```plaintext
2017-12-22 15:54:55 +00:00
GET /users?with_custom_attributes=true
```
2012-07-05 13:57:45 +00:00
## Single user
2021-09-30 18:11:31 +00:00
Get a single user.
2012-07-05 13:57:45 +00:00
2014-06-25 07:18:52 +00:00
### For user
2014-06-13 15:02:42 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2014-06-13 15:02:42 +00:00
GET /users/:id
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
| `id` | integer | yes | The ID of a user |
2014-06-13 15:02:42 +00:00
```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",
2020-07-13 12:09:18 +00:00
"bio": "",
2021-02-01 12:09:03 +00:00
"bot": false,
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": "",
2020-03-03 09:07:54 +00:00
"organization": "",
2021-02-15 21:08:59 +00:00
"job_title": "Operations Specialist",
2022-04-14 18:08:29 +00:00
"pronouns": "he/him",
"work_information": null,
2021-02-15 21:08:59 +00:00
"followers": 1,
2022-04-14 18:08:29 +00:00
"following": 1,
2022-05-04 09:09:02 +00:00
"local_time": "3:38 PM",
"is_followed": false
2014-06-13 15:02:42 +00:00
}
```
2022-05-11 15:07:26 +00:00
### For administrator
2014-06-13 15:02:42 +00:00
2022-03-22 12:07:28 +00:00
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
2020-02-29 03:07:51 +00:00
```plaintext
2012-07-05 13:57:45 +00:00
GET /users/:id
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
| `id` | integer | yes | 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,
2020-07-13 12:09:18 +00:00
"bio": "",
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": "",
2020-03-03 09:07:54 +00:00
"job_title": "Operations Specialist",
2022-04-14 18:08:29 +00:00
"pronouns": "he/him",
"work_information": null,
"followers": 1,
"following": 1,
"local_time": "3:38 PM",
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",
2020-05-28 09:08:05 +00:00
"note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
2016-05-01 20:48:26 +00:00
"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,
2021-04-07 18:09:45 +00:00
"commit_email": "john-codes@example.com",
2020-01-24 00:08:51 +00:00
"current_sign_in_ip": "196.165.1.102",
2020-03-12 12:09:17 +00:00
"last_sign_in_ip": "172.127.2.22",
"plan": "gold",
2020-07-30 15:09:40 +00:00
"trial": true,
2022-03-22 12:07:28 +00:00
"sign_in_count": 1337,
"namespace_id": 1
2012-07-05 13:57:45 +00:00
}
```
2020-12-04 21:09:29 +00:00
NOTE:
2020-07-16 06:09:33 +00:00
The `plan` and `trial` parameters are only available on GitLab Enterprise Edition.
2020-03-12 12:09:17 +00:00
2021-09-07 03:11:39 +00:00
Users on [GitLab Premium or higher ](https://about.gitlab.com/pricing/ ) also see
2021-05-10 09:10:28 +00:00
the `shared_runners_minutes_limit` , `is_auditor` , and `extra_shared_runners_minutes_limit` parameters.
2019-07-04 08:22:41 +00:00
```json
{
"id": 1,
"username": "john_smith",
2021-05-10 09:10:28 +00:00
"is_auditor": false,
2019-07-04 08:22:41 +00:00
"shared_runners_minutes_limit": 133,
2019-07-16 09:22:40 +00:00
"extra_shared_runners_minutes_limit": 133,
2019-07-04 08:22:41 +00:00
...
}
```
2021-09-07 03:11:39 +00:00
Users on [GitLab.com Premium or higher ](https://about.gitlab.com/pricing/ ) also
2021-05-26 06:10:25 +00:00
see the `group_saml` option and `provisioned_by_group_id` parameter:
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,
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}
],
2021-05-26 06:10:25 +00:00
"provisioned_by_group_id": 123789
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:
2020-02-29 03:07:51 +00:00
```plaintext
2017-12-22 15:54:55 +00:00
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
2022-03-22 12:07:28 +00:00
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
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.
2021-07-28 21:08:53 +00:00
`force_random_password` and `reset_password` take priority
2019-06-27 19:41:51 +00:00
over `password` . In addition, `reset_password` and
`force_random_password` can be used together.
2012-10-02 09:52:13 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-11-19 21:09:07 +00:00
From [GitLab 12.1 ](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/ ), `private_profile` defaults to `false` .
2019-07-19 09:53:19 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-11-19 21:09:07 +00:00
From [GitLab 13.2 ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604 ), `bio` defaults to `""` instead of `null` .
2020-07-13 12:09:18 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2012-10-02 09:52:13 +00:00
POST /users
```
Parameters:
2020-02-27 21:09:17 +00:00
| Attribute | Required | Description |
2020-06-04 00:08:17 +00:00
| :----------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
2022-05-11 15:07:26 +00:00
| `admin` | No | User is an administrator - true or false (default) |
2020-02-27 21:09:17 +00:00
| `avatar` | No | Image file for user's avatar |
| `bio` | No | User's biography |
| `can_create_group` | No | User can create groups - true or false |
| `color_scheme_id` | No | User's color scheme for the file viewer (see [the user preference docs ](../user/profile/preferences.md#syntax-highlighting-theme ) for more information) |
| `email` | Yes | Email |
| `extern_uid` | No | External UID |
| `external` | No | Flags the user as external - true or false (default) |
2021-12-20 18:13:27 +00:00
| `extra_shared_runners_minutes_limit` ** (PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. |
2020-02-27 21:09:17 +00:00
| `force_random_password` | No | Set user password to a random value - true or false (default) |
| `group_id_for_saml` | No | ID of group where SAML has been configured |
| `linkedin` | No | LinkedIn |
| `location` | No | User's location |
2020-03-21 00:09:18 +00:00
| `name` | Yes | Name |
2022-05-11 15:07:26 +00:00
| `note` | No | Administrator notes for this user |
2020-02-27 21:09:17 +00:00
| `organization` | No | Organization name |
| `password` | No | Password |
2020-12-16 15:10:18 +00:00
| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) |
2020-02-27 21:09:17 +00:00
| `projects_limit` | No | Number of projects user can create |
| `provider` | No | External provider name |
| `reset_password` | No | Send user password reset link - true or false(default) |
2021-12-20 18:13:27 +00:00
| `shared_runners_minutes_limit` ** (PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0` . |
2020-02-27 21:09:17 +00:00
| `skip_confirmation` | No | Skip confirmation - true or false (default) |
| `skype` | No | Skype ID |
| `theme_id` | No | The GitLab theme for the user (see [the user preference docs ](../user/profile/preferences.md#navigation-theme ) for more information) |
| `twitter` | No | Twitter account |
| `username` | Yes | Username |
2021-02-25 06:10:51 +00:00
| `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page |
2020-02-27 21:09:17 +00:00
| `website_url` | No | Website URL |
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
2022-03-22 12:07:28 +00:00
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
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
2020-02-29 03:07:51 +00:00
```plaintext
2012-12-18 19:24:31 +00:00
PUT /users/:id
```
Parameters:
2013-02-20 11:10:51 +00:00
2020-02-27 21:09:17 +00:00
| Attribute | Required | Description |
2020-06-04 00:08:17 +00:00
| :----------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
2022-05-11 15:07:26 +00:00
| `admin` | No | User is an administrator - true or false (default) |
2020-02-27 21:09:17 +00:00
| `avatar` | No | Image file for user's avatar |
| `bio` | No | User's biography |
| `can_create_group` | No | User can create groups - true or false |
| `color_scheme_id` | No | User's color scheme for the file viewer (see [the user preference docs ](../user/profile/preferences.md#syntax-highlighting-theme ) for more information) |
| `email` | No | Email |
| `extern_uid` | No | External UID |
| `external` | No | Flags the user as external - true or false (default) |
2021-12-20 18:13:27 +00:00
| `extra_shared_runners_minutes_limit` ** (PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. |
2020-02-27 21:09:17 +00:00
| `group_id_for_saml` | No | ID of group where SAML has been configured |
| `id` | Yes | The ID of the user |
| `linkedin` | No | LinkedIn |
| `location` | No | User's location |
| `name` | No | Name |
2022-05-11 15:07:26 +00:00
| `note` | No | Administration notes for this user |
2020-02-27 21:09:17 +00:00
| `organization` | No | Organization name |
| `password` | No | Password |
2020-12-16 15:10:18 +00:00
| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) |
2020-02-27 21:09:17 +00:00
| `projects_limit` | No | Limit projects each user can create |
| `provider` | No | External provider name |
2021-04-07 18:09:45 +00:00
| `public_email` | No | The public email of the user (must be already verified) |
2021-12-20 18:13:27 +00:00
| `shared_runners_minutes_limit` ** (PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` . |
2020-02-27 21:09:17 +00:00
| `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) |
| `skype` | No | Skype ID |
| `theme_id` | No | The GitLab theme for the user (see [the user preference docs ](../user/profile/preferences.md#navigation-theme ) for more information) |
| `twitter` | No | Twitter account |
| `username` | No | Username |
2021-02-25 06:10:51 +00:00
| `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page |
2020-02-27 21:09:17 +00:00
| `website_url` | No | Website URL |
2014-06-25 07:18:52 +00:00
2020-11-19 21:09:07 +00:00
On password update, the user is 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,
2020-02-27 09:09:01 +00:00
even in cases where a `409` (Conflict) would be more appropriate.
For example, when renaming the email address to some existing one.
2012-12-18 19:24:31 +00:00
2020-02-14 12:09:03 +00:00
## Delete authentication identity from user
Deletes a user's authentication identity using the provider name associated with that identity. Available only for administrators.
2020-02-29 03:07:51 +00:00
```plaintext
2020-02-14 12:09:03 +00:00
DELETE /users/:id/identities/:provider
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|------------------------|
| `id` | integer | yes | The ID of a user |
| `provider` | string | yes | External provider name |
2020-02-14 12:09:03 +00:00
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
2020-02-29 03:07:51 +00:00
```plaintext
2012-12-18 19:24:31 +00:00
DELETE /users/:id
```
2013-02-20 11:10:51 +00:00
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|---------------|---------|----------|----------------------------------------------|
| `id` | integer | yes | The ID of a user |
2022-01-28 03:15:57 +00:00
| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User ](../user/profile/account/delete_account.md#associated-records ) are 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
2020-02-29 03:07:51 +00:00
```plaintext
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",
2020-07-13 12:09:18 +00:00
"bio": "",
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": "",
2022-04-14 18:08:29 +00:00
"job_title": "",
"pronouns": "he/him",
"bot": false,
"work_information": null,
"followers": 0,
"following": 0,
"local_time": "3:38 PM",
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,
2022-04-14 18:08:29 +00:00
"private_profile": false,
"commit_email": "admin@example.com",
2012-07-05 13:57:45 +00:00
}
```
2012-09-21 11:49:28 +00:00
2022-04-14 18:08:29 +00:00
Users on [GitLab Premium or higher ](https://about.gitlab.com/pricing/ ) also see the `shared_runners_minutes_limit` , `extra_shared_runners_minutes_limit` parameters.
2022-05-11 15:07:26 +00:00
## List current user (for administrators)
2016-11-21 12:59:37 +00:00
2022-03-22 12:07:28 +00:00
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
2020-02-29 03:07:51 +00:00
```plaintext
2016-11-21 12:59:37 +00:00
GET /user
```
2021-11-22 18:10:55 +00:00
Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|--------------------------------------------------|
| `sudo` | integer | no | the ID of a user to make the call in their place |
2016-11-21 12:59:37 +00:00
```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",
2022-03-17 06:08:26 +00:00
"is_admin": true,
2020-07-13 12:09:18 +00:00
"bio": "",
2016-11-21 12:59:37 +00:00
"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": "",
2020-03-03 09:07:54 +00:00
"job_title": "",
2016-11-21 12:59:37 +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",
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,
2021-04-07 18:09:45 +00:00
"commit_email": "john-codes@example.com",
2020-01-24 00:08:51 +00:00
"current_sign_in_ip": "196.165.1.102",
2022-03-22 12:07:28 +00:00
"last_sign_in_ip": "172.127.2.22",
2022-04-14 18:08:29 +00:00
"namespace_id": 1,
"note": null
2016-11-21 12:59:37 +00:00
}
```
2021-09-07 03:11:39 +00:00
Users on [GitLab Premium or higher ](https://about.gitlab.com/pricing/ ) also see these
2021-05-26 06:10:25 +00:00
parameters:
- `shared_runners_minutes_limit`
- `extra_shared_runners_minutes_limit`
- `is_auditor`
- `provisioned_by_group_id`
- `using_license_seat`
2021-05-10 09:10:28 +00:00
2018-07-13 15:52:31 +00:00
## User status
Get the status of the currently signed in user.
2020-02-29 03:07:51 +00:00
```plaintext
2018-07-13 15:52:31 +00:00
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",
2021-04-19 18:09:09 +00:00
"availability":"busy",
2018-07-26 15:14:02 +00:00
"message":"I crave coffee :coffee:",
2021-02-16 12:09:03 +00:00
"message_html": "I crave coffee < gl-emoji title = \"hot beverage \" data-name = \"coffee \" data-unicode-version = \"4.0 \"> ☕</ gl-emoji > ",
"clear_status_at": null
2018-07-13 15:52:31 +00:00
}
```
## Get the status of a user
2021-08-26 03:09:01 +00:00
Get the status of a user. This endpoint can be accessed without authentication.
2018-07-13 15:52:31 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2018-07-13 15:52:31 +00:00
GET /users/:id_or_username/status
```
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------- |
2020-05-07 06:09:38 +00:00
| `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",
2021-04-19 18:09:09 +00:00
"availability":"busy",
2018-07-26 15:14:02 +00:00
"message":"I crave coffee :coffee:",
2021-02-16 12:09:03 +00:00
"message_html": "I crave coffee < gl-emoji title = \"hot beverage \" data-name = \"coffee \" data-unicode-version = \"4.0 \"> ☕</ gl-emoji > ",
"clear_status_at": null
2018-07-13 15:52:31 +00:00
}
```
2022-02-15 00:15:45 +00:00
## Set user status
Set the status of the current user.
```plaintext
PUT /user/status
```
| Attribute | Type | Required | Description |
| -------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index ](https://github.com/bonusly/gemojione/blob/master/config/index.json ). |
| `message` | string | no | The message to set as a status. It can also contain emoji codes. |
| `clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes` , `3_hours` , `8_hours` , `1_day` , `3_days` , `7_days` , `30_days`
When both parameters `emoji` and `message` are empty, the status is cleared. When the `clear_status_after` parameter is missing from the request, the previously set value for `"clear_status_after` is cleared.
```shell
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " --data "clear_status_after=1_day" --data "emoji=coffee" \
--data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status"
```
Example responses
```json
{
"emoji":"coffee",
"message":"I crave coffee",
"message_html": "I crave coffee",
"clear_status_at":"2021-02-15T10:49:01.311Z"
}
```
2021-06-09 03:10:22 +00:00
## Get user preferences
Get a list of currently authenticated user's preferences.
```plaintext
GET /user/preferences
```
Example response:
```json
{
"id": 1,
"user_id": 1
"view_diffs_file_by_file": true,
"show_whitespace_in_diffs": false
}
```
Parameters:
- **none**
2021-04-02 21:09:22 +00:00
## User preference modification
Update the current user's preferences.
```plaintext
PUT /user/preferences
```
```json
{
"id": 1,
"user_id": 1
2021-06-09 03:10:22 +00:00
"view_diffs_file_by_file": true,
"show_whitespace_in_diffs": false
2021-04-02 21:09:22 +00:00
}
```
Parameters:
| Attribute | Required | Description |
| :--------------------------- | :------- | :---------------------------------------------------------- |
| `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. |
2021-06-09 03:10:22 +00:00
| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. |
2021-04-02 21:09:22 +00:00
2021-02-15 21:08:59 +00:00
## User Follow
### Follow and unfollow users
Follow a user.
```plaintext
POST /users/:id/follow
```
Unfollow a user.
```plaintext
POST /users/:id/unfollow
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------- |
| `id` | integer | yes | The ID of the user to follow |
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/users/3/follow"
```
Example response:
```json
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"web_url": "http://localhost:3000/john_smith"
}
```
### Followers and following
2021-09-30 18:11:31 +00:00
Get the followers of a user.
2021-02-15 21:08:59 +00:00
```plaintext
GET /users/:id/followers
```
Get the list of users being followed.
```plaintext
GET /users/:id/following
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------- |
| `id` | integer | yes | The ID of the user to follow |
```shell
curl --request GET --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/users/3/followers"
```
Example response:
```json
[
{
"id": 2,
"name": "Lennie Donnelly",
"username": "evette.kilback",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/7955171a55ac4997ed81e5976287890a?s=80& d=identicon",
"web_url": "http://127.0.0.1:3000/evette.kilback"
},
{
"id": 4,
"name": "Serena Bradtke",
"username": "cammy",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/a2daad869a7b60d3090b7b9bef4baf57?s=80& d=identicon",
"web_url": "http://127.0.0.1:3000/cammy"
}
]
```
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
2021-07-30 21:10:15 +00:00
| Attribute | Type | Description |
| --------------------------------- | ------ | ---------------------------------------------------------------------------- |
| `assigned_issues` | number | Number of issues that are open and assigned to the current user. [Added ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66909 ) in GitLab 14.2. |
| `assigned_merge_requests` | number | Number of merge requests that are active and assigned to the current user. [Added ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50026 ) in GitLab 13.8. |
| `merge_requests` | number | [Deprecated ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50026 ) in GitLab 13.8. Equivalent to and replaced by `assigned_merge_requests` . |
| `review_requested_merge_requests` | number | Number of merge requests that the current user has been requested to review. [Added ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50026 ) in GitLab 13.8. |
| `todos` | number | Number of pending to-do items for current user. [Added ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66909 ) in GitLab 14.2. |
2019-07-09 08:44:19 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2019-07-09 08:44:19 +00:00
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
{
2021-07-30 21:10:15 +00:00
"merge_requests": 4,
"assigned_issues": 15,
"assigned_merge_requests": 11,
"review_requested_merge_requests": 0,
"todos": 1
2019-07-09 08:44:19 +00:00
}
```
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.
2020-02-29 03:07:51 +00:00
```plaintext
2012-09-21 11:49:28 +00:00
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-02-29 03:07:51 +00:00
```plaintext
2020-01-20 09:08:32 +00:00
GET /users/:id_or_username/keys
2014-04-15 14:39:46 +00:00
```
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------------- |
2020-05-07 06:09:38 +00:00
| `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.
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
GET /user/keys/:key_id
2012-09-21 11:49:28 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|--------|----------|----------------------|
| `key_id` | string | yes | The ID of an SSH key |
2012-09-21 11:49:28 +00:00
2022-03-03 12:14:02 +00:00
```json
{
"id": 1,
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
}
```
## Single SSH key for given user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81790) in GitLab 14.9.
Get a single key for a given user.
```plaintext
GET /users/:id/keys/:key_id
```
Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
| `key_id` | integer | yes | SSH key ID |
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
2020-02-29 03:07:51 +00:00
```plaintext
2012-09-21 11:49:28 +00:00
POST /user/keys
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|--------------|--------|----------|--------------------------------------------------------------------------------|
| `title` | string | yes | new SSH key's title |
| `key` | string | yes | new SSH key |
| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
2012-09-21 11:49:28 +00:00
2015-01-21 17:57:54 +00:00
```json
{
"title": "ABC",
2020-06-04 00:08:17 +00:00
"key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
"expires_at": "2016-01-21T00:00:00.000Z"
2015-01-21 17:57:54 +00:00
}
```
2020-11-19 21:09:07 +00:00
Returns a created key with status `201 Created` on success. If an
2015-01-21 18:08:15 +00:00
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
2021-09-22 12:12:04 +00:00
Create new key owned by specified user. Available only for administrator.
2013-03-06 04:48:40 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2013-03-06 04:48:40 +00:00
POST /users/:id/keys
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|--------------|---------|----------|--------------------------------------------------------------------------------|
| `id` | integer | yes | ID of specified user |
| `title` | string | yes | new SSH key's title |
| `key` | string | yes | new SSH key |
| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
2013-03-06 04:48:40 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-09-07 15:09:04 +00:00
This also adds an audit event, as described in [audit instance events ](../administration/audit_events.md#instance-events ). ** (PREMIUM)**
2020-06-19 15:08:39 +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
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
DELETE /user/keys/:key_id
2012-09-21 11:49:28 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|-------------|
| `key_id` | integer | yes | 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
2021-09-22 12:12:04 +00:00
Deletes key owned by a specified user. Available only for administrator.
2014-04-15 14:39:46 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
DELETE /users/:id/keys/:key_id
2014-04-15 14:39:46 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
| `key_id` | integer | yes | 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.
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
GET /user/gpg_keys
```
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +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.
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
GET /user/gpg_keys/:key_id
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2019-07-04 08:22:41 +00:00
| `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
2020-05-28 00:08:37 +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.
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
POST /user/gpg_keys
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
2021-11-22 18:10:55 +00:00
|-----------|--------|----------|-----------------|
| `key` | string | yes | The new GPG key |
2017-09-05 09:32:27 +00:00
2020-01-30 15:09:15 +00:00
```shell
2021-06-02 15:09:59 +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.
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
DELETE /user/gpg_keys/:key_id
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2019-07-04 08:22:41 +00:00
| `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
2020-05-28 00:08:37 +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
2020-09-30 00:09:53 +00:00
Get a list of a specified user's GPG keys. This endpoint can be accessed without authentication.
2017-09-05 09:32:27 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
GET /users/:id/gpg_keys
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------ |
2019-07-04 08:22:41 +00:00
| `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
2020-05-28 00:08:37 +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
2020-10-07 18:08:34 +00:00
Get a specific GPG key for a given user. [Introduced ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43693 )
2021-09-22 12:12:04 +00:00
in GitLab 13.5, this endpoint can be accessed without administrator authentication.
2017-09-05 09:32:27 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
GET /users/:id/gpg_keys/:key_id
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer | yes | The ID of the user |
2019-07-04 08:22:41 +00:00
| `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
2020-05-28 00:08:37 +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
2021-09-22 12:12:04 +00:00
Create new GPG key owned by the specified user. Available only for administrator.
2017-09-05 09:32:27 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
POST /users/:id/gpg_keys
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer | yes | The ID of the user |
2019-07-04 08:22:41 +00:00
| `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
2021-06-02 15:09:59 +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
2021-09-22 12:12:04 +00:00
Delete a GPG key owned by a specified user. Available only for administrator.
2017-09-05 09:32:27 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-09-05 09:32:27 +00:00
DELETE /users/:id/gpg_keys/:key_id
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer | yes | The ID of the user |
2019-07-04 08:22:41 +00:00
| `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
2020-05-28 00:08:37 +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.
2020-12-04 21:09:29 +00:00
NOTE:
2020-07-24 21:09:16 +00:00
Due to [a bug ](https://gitlab.com/gitlab-org/gitlab/-/issues/25077 ) this endpoint currently
does not return the primary email address.
2020-02-29 03:07:51 +00:00
```plaintext
2015-07-29 13:40:08 +00:00
GET /user/emails
```
```json
[
{
"id": 1,
2021-04-09 21:09:22 +00:00
"email": "email@example.com",
"confirmed_at" : "2021-03-26T19:07:56.248Z"
2015-07-29 13:40:08 +00:00
},
{
"id": 3,
2021-04-09 21:09:22 +00:00
"email": "email2@example.com",
"confirmed_at" : null
2015-07-29 13:40:08 +00:00
}
]
```
Parameters:
- **none**
## List emails for user
2021-09-22 12:12:04 +00:00
Get a list of a specified user's emails. Available only for administrator
2015-07-29 13:40:08 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-07-24 21:09:16 +00:00
Due to [a bug ](https://gitlab.com/gitlab-org/gitlab/-/issues/25077 ) this endpoint currently
does not return the primary email address.
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
GET /users/:id/emails
2015-07-29 13:40:08 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|---------|----------|----------------------|
| `id` | integer | yes | 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
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
GET /user/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|-------------|
| `email_id` | integer | yes | Email ID |
2015-07-29 13:40:08 +00:00
```json
{
"id": 1,
2021-04-09 21:09:22 +00:00
"email": "email@example.com",
"confirmed_at" : "2021-03-26T19:07:56.248Z"
2015-07-29 13:40:08 +00:00
}
```
## Add email
Creates a new email owned by the currently authenticated user.
2020-02-29 03:07:51 +00:00
```plaintext
2015-07-29 13:40:08 +00:00
POST /user/emails
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|-----------|--------|----------|-------------|
| `email` | string | yes | Email address |
2015-07-29 13:40:08 +00:00
```json
{
"id": 4,
2021-04-09 21:09:22 +00:00
"email": "email@example.com",
"confirmed_at" : "2021-03-26T19:07:56.248Z"
2015-07-29 13:40:08 +00:00
}
```
2020-11-19 21:09:07 +00:00
Returns a 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
2021-09-22 12:12:04 +00:00
Create new email owned by specified user. Available only for administrator
2015-07-29 13:40:08 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2015-07-29 13:40:08 +00:00
POST /users/:id/emails
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|---------------------|---------|----------|---------------------------------------------------------------------------|
| `id` | string | yes | ID of specified user |
| `email` | string | yes | Email address |
| `skip_confirmation` | boolean | no | Skip confirmation and assume email is verified - true or false (default) |
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
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
DELETE /user/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|-------------|
| `email_id` | integer | yes | Email ID |
2015-07-29 13:40:08 +00:00
## Delete email for given user
2021-09-22 12:12:04 +00:00
Deletes email owned by a specified user. Available only for administrator.
2015-07-29 13:40:08 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2016-10-27 08:20:06 +00:00
DELETE /users/:id/emails/:email_id
2015-07-29 13:40:08 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
| `email_id` | integer | yes | Email ID |
2015-07-29 13:40:08 +00:00
2015-04-28 16:02:44 +00:00
## Block user
2021-09-22 12:12:04 +00:00
Blocks the specified user. Available only for administrator.
2015-04-28 16:02:44 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-02-20 12:31:11 +00:00
POST /users/:id/block
2015-04-28 16:02:44 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
2015-04-28 16:02:44 +00:00
2020-03-04 12:07:52 +00:00
Returns:
- `201 OK` on success.
- `404 User Not Found` if user cannot be found.
2020-10-13 06:09:09 +00:00
- `403 Forbidden` when trying to block:
- A user that is blocked through LDAP.
- An internal user.
2015-04-28 16:02:44 +00:00
## Unblock user
2021-09-22 12:12:04 +00:00
Unblocks the specified user. Available only for administrator.
2015-04-28 16:02:44 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-02-20 12:31:11 +00:00
POST /users/:id/unblock
2015-04-28 16:02:44 +00:00
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
2015-04-28 16:02:44 +00:00
2020-11-19 21:09:07 +00:00
Returns `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-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4.
2019-10-10 00:06:44 +00:00
2021-09-22 12:12:04 +00:00
Deactivates the specified user. Available only for administrator.
2019-10-10 00:06:44 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2019-10-10 00:06:44 +00:00
POST /users/:id/deactivate
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
2019-10-10 00:06:44 +00:00
Returns:
- `201 OK` on success.
- `404 User Not Found` if user cannot be found.
- `403 Forbidden` when trying to deactivate a user:
2021-09-22 12:12:04 +00:00
- Blocked by administrator or by LDAP synchronization.
2020-10-19 21:09:06 +00:00
- That has any activity in past 90 days. These users cannot be deactivated.
2020-10-14 06:08:33 +00:00
- That is internal.
2019-10-10 00:06:44 +00:00
## Activate user
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4.
2019-10-10 00:06:44 +00:00
2021-09-22 12:12:04 +00:00
Activates the specified user. Available only for administrator.
2019-10-10 00:06:44 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2019-10-10 00:06:44 +00:00
POST /users/:id/activate
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
2019-10-10 00:06:44 +00:00
Returns:
- `201 OK` on success.
2020-11-23 12:09:11 +00:00
- `404 User Not Found` if the user cannot be found.
- `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization.
2019-10-10 00:06:44 +00:00
2021-08-26 09:11:15 +00:00
## Ban user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3.
2021-09-22 12:12:04 +00:00
Bans the specified user. Available only for administrator.
2021-08-26 09:11:15 +00:00
```plaintext
POST /users/:id/ban
```
Parameters:
- `id` (required) - ID of specified user
Returns:
- `201 OK` on success.
- `404 User Not Found` if user cannot be found.
- `403 Forbidden` when trying to ban a user that is not active.
## Unban user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3.
2021-09-22 12:12:04 +00:00
Unbans the specified user. Available only for administrator.
2021-08-26 09:11:15 +00:00
```plaintext
POST /users/:id/unban
```
Parameters:
- `id` (required) - ID of specified user
Returns:
- `201 OK` on success.
- `404 User Not Found` if the user cannot be found.
- `403 Forbidden` when trying to unban a user that is not banned.
2022-04-12 03:09:50 +00:00
## Get user contribution events
2016-10-10 11:35:26 +00:00
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
2022-02-02 15:17:50 +00:00
Requires administrator access.
2017-03-17 14:23:52 +00:00
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
2020-02-29 03:07:51 +00:00
```plaintext
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
2020-02-29 03:07:51 +00:00
```shell
2020-05-28 00:08:37 +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,
2020-08-06 21:10:15 +00:00
"user_id" : 2,
2017-03-17 14:23:52 +00:00
"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,
2020-08-06 21:10:15 +00:00
"user_id" : 2,
2017-03-17 14:23:52 +00:00
"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
]
```
2020-11-23 12:09:11 +00:00
## Approve user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263107) in GitLab 13.7.
Approves the specified user. Available only for administrators.
```plaintext
POST /users/:id/approve
```
Parameters:
2021-11-22 18:10:55 +00:00
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
2020-11-23 12:09:11 +00:00
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/42/approve"
```
Returns:
2021-08-13 06:10:15 +00:00
- `201 Created` on success.
2020-11-23 12:09:11 +00:00
- `404 User Not Found` if user cannot be found.
- `403 Forbidden` if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization.
2021-11-24 21:12:47 +00:00
- `409 Conflict` if the user has been deactivated.
2020-11-23 12:09:11 +00:00
Example Responses:
```json
{ "message": "Success" }
```
```json
{ "message": "404 User Not Found" }
```
```json
2021-01-25 15:09:00 +00:00
{ "message": "The user you are trying to approve is not pending approval" }
2020-11-23 12:09:11 +00:00
```
2021-09-09 09:11:16 +00:00
## Reject user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339925) in GitLab 14.3.
Rejects specified user that is [pending approval ](../user/admin_area/moderate_users.md#users-pending-approval ). Available only for administrators.
```plaintext
POST /users/:id/reject
```
Parameters:
- `id` (required) - ID of specified user
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/42/reject"
```
Returns:
- `200 OK` on success.
- `403 Forbidden` if not authenticated as an administrator.
- `404 User Not Found` if user cannot be found.
- `409 Conflict` if user is not pending approval.
Example Responses:
```json
{ "message": "Success" }
```
```json
{ "message": "404 User Not Found" }
```
```json
{ "message": "User does not have a pending request" }
```
2017-03-17 14:23:52 +00:00
## Get an impersonation token of a user
2017-02-09 15:21:09 +00:00
2021-09-22 12:12:04 +00:00
> Requires administrators permissions.
2017-03-17 14:23:52 +00:00
It shows a user's impersonation token.
2017-02-09 15:21:09 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
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
2020-02-29 03:07:51 +00:00
```shell
2020-05-28 00:08:37 +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,
2020-08-06 21:10:15 +00:00
"user_id" : 2,
2017-03-17 14:23:52 +00:00
"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
2022-02-02 15:17:50 +00:00
Requires administrator access. Token values are returned once. Make sure you save it because you can't access
it again.
2018-11-08 15:03:56 +00:00
2021-07-28 21:08:53 +00:00
It creates a new impersonation token. 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
2020-11-19 21:09:07 +00:00
both API calls and Git reads and writes. The user can't see these tokens in their profile
2017-02-09 15:21:09 +00:00
settings page.
2017-01-04 10:51:17 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2017-03-01 16:59:03 +00:00
POST /users/:user_id/impersonation_tokens
2017-01-04 10:51:17 +00:00
```
2020-06-04 00:08:17 +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
2020-02-29 03:07:51 +00:00
```shell
2021-06-02 15:09:59 +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,
2020-08-06 21:10:15 +00:00
"user_id" : 2,
2017-03-17 14:23:52 +00:00
"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
2022-02-02 15:17:50 +00:00
Requires administrator access.
2017-03-17 14:23:52 +00:00
It revokes an impersonation token.
2017-01-04 10:51:17 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
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
```
Parameters:
2020-06-04 00:08:17 +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-04-12 11:19:45 +00:00
2021-11-22 18:10:55 +00:00
```shell
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
```
2021-01-28 06:08:59 +00:00
## Create a personal access token **(FREE SELF)**
2020-11-16 12:09:05 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6.
2020-12-24 12:10:03 +00:00
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267553) in GitLab 13.8.
2020-11-16 12:09:05 +00:00
2020-12-24 15:09:57 +00:00
Use this API to create a new personal access token. Token values are returned once so,
make sure you save it as you can't access it again. This API can only be used by
GitLab administrators.
2020-11-16 12:09:05 +00:00
```plaintext
POST /users/:user_id/personal_access_tokens
```
| Attribute | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `user_id` | integer | yes | The ID of the user |
| `name` | string | yes | The name of the personal access token |
| `expires_at` | date | no | The expiration date of the personal access token in ISO format (`YYYY-MM-DD`) |
2022-04-06 00:08:33 +00:00
| `scopes` | array | yes | The array of scopes of the personal access token. See [personal access token scopes ](../user/profile/personal_access_tokens.md#personal-access-token-scopes ) for possible values. |
2020-11-16 12:09:05 +00:00
```shell
2021-06-02 15:09:59 +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/personal_access_tokens"
2020-11-16 12:09:05 +00:00
```
Example response:
```json
{
"id": 3,
"name": "mytoken",
"revoked": false,
"created_at": "2020-10-14T11:58:53.526Z",
"scopes": [
"api"
],
"user_id": 42,
"active": true,
"expires_at": "2020-12-31",
"token": "ggbfKkC4n-Lujy8jwCR2"
}
```
2022-05-11 15:07:26 +00:00
## Get user activities (administrator only)
2017-04-12 11:19:45 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-07-16 06:09:33 +00:00
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)
2020-05-21 03:08:00 +00:00
- User logging in to GitLab
2022-01-25 12:14:14 +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)
2020-02-10 15:08:54 +00:00
- User using the API
2020-05-14 15:08:14 +00:00
- User using the GraphQL API
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.
2020-02-29 03:07:51 +00:00
```plaintext
2017-04-12 11:19:45 +00:00
GET /user/activities
```
Parameters:
2020-06-04 00:08:17 +00:00
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `from` | string | no | Date string in the format YEAR-MONTH-DAY. For example, `2016-03-11` . Defaults to 6 months ago. |
2017-04-12 11:19:45 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +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
```
2021-07-23 18:10:06 +00:00
`last_activity_at` is deprecated. Use `last_activity_on` instead.
2020-01-22 15:08:48 +00:00
2022-05-11 15:07:26 +00:00
## User memberships (administrator only)
2020-01-22 15:08:48 +00:00
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20532) in GitLab 12.8.
2020-01-22 15:08:48 +00:00
2021-09-22 12:12:04 +00:00
Lists all projects and groups a user is a member of. This endpoint is available for administrators only.
2020-01-22 15:08:48 +00:00
It returns the `source_id` , `source_name` , `source_type` and `access_level` of a membership.
2020-02-26 03:09:07 +00:00
Source can be of type `Namespace` (representing a group) or `Project` . The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included.
Access levels are represented by an integer value. For more details, read about the meaning of [access level values ](access_requests.md#valid-access-levels ).
2020-01-22 15:08:48 +00:00
2020-02-26 03:09:07 +00:00
```plaintext
2020-01-22 15:08:48 +00:00
GET /users/:id/memberships
```
Parameters:
2020-06-04 00:08:17 +00:00
| 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` |
2020-01-22 15:08:48 +00:00
Returns:
- `200 OK` on success.
2020-02-26 03:09:07 +00:00
- `404 User Not Found` if user can't be found.
2021-09-22 12:12:04 +00:00
- `403 Forbidden` when not requested by an administrator.
2020-01-22 15:08:48 +00:00
- `400 Bad Request` when requested type is not supported.
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/:user_id/memberships"
2020-01-22 15:08:48 +00:00
```
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"
2021-04-29 12:09:58 +00:00
}
2020-01-22 15:08:48 +00:00
]
```
2022-06-20 09:09:39 +00:00
## Disable two factor authentication (administrator only)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2.
Disables two factor authentication (2FA) for the specified user. Only administrators can disable 2FA for users.
Administrators cannot disable 2FA for their own user account or other administrators using the API. Instead, they can disable an
administrator's 2FA [using the Rails console ](../security/two_factor_authentication.md#for-a-single-user ).
```plaintext
2022-06-21 06:08:28 +00:00
PATCH /users/:id/disable_two_factor
2022-06-20 09:09:39 +00:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer | yes | The ID of the user |
```shell
2022-06-21 06:08:28 +00:00
curl --request PATCH --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/1/disable_two_factor"
2022-06-20 09:09:39 +00:00
```
Returns:
- `204 No content` on success.
- `400 Bad request` if two factor authentication is not enabled for the specified user.
- `403 Forbidden` if not authenticated as an administrator.
- `404 User Not Found` if user cannot be found.