debian-mirror-gitlab/doc/api/users.md

1367 lines
39 KiB
Markdown
Raw Normal View History

2017-09-10 17:25:29 +05:30
# Users API
2014-09-02 18:07:02 +05:30
## List users
2019-09-30 21:07:59 +05:30
Active users = Total accounts - Blocked users
2014-09-02 18:07:02 +05:30
Get a list of users.
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
### For normal users
```
GET /users
```
```json
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/john_smith"
2014-09-02 18:07:02 +05:30
},
{
"id": 2,
"username": "jack_smith",
"name": "Jack Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/jack_smith"
2014-09-02 18:07:02 +05:30
}
]
```
2019-07-31 22:56:46 +05:30
You can also search for users by name or primary email using `?search=`. For example. `/users?search=John`.
2018-11-18 11:00:15 +05:30
In addition, you can lookup users by username:
```
GET /users?username=:username
```
For example:
```
GET /users?username=jack_smith
```
2017-08-17 22:00:37 +05:30
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-12-13 13:39:08 +05:30
NOTE: **Note:**
Username search is case insensitive.
2014-09-02 18:07:02 +05:30
### For admins
```
GET /users
```
2019-09-30 21:07:59 +05:30
| 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-03-17 18:26:18 +05:30
2014-09-02 18:07:02 +05:30
```json
[
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
2016-06-02 11:05:42 +05:30
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/john_smith",
2014-09-02 18:07:02 +05:30
"created_at": "2012-05-23T08:00:58Z",
2016-06-02 11:05:42 +05:30
"is_admin": false,
2014-09-02 18:07:02 +05:30
"bio": null,
2016-06-02 11:05:42 +05:30
"location": null,
2014-09-02 18:07:02 +05:30
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
2016-11-03 12:29:30 +05:30
"organization": "",
2016-06-02 11:05:42 +05:30
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2018-03-17 18:26:18 +05:30
"theme_id": 1,
2017-08-17 22:00:37 +05:30
"last_activity_on": "2012-05-23",
2014-09-02 18:07:02 +05:30
"color_scheme_id": 2,
2016-06-02 11:05:42 +05:30
"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-09-11 14:41:01 +05:30
"can_create_group": true,
2016-06-02 11:05:42 +05:30
"can_create_project": true,
"two_factor_enabled": true,
2018-11-18 11:00:15 +05:30
"external": false,
"private_profile": false
2014-09-02 18:07:02 +05:30
},
{
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
"state": "blocked",
2016-06-02 11:05:42 +05:30
"avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/jack_smith",
2014-09-02 18:07:02 +05:30
"created_at": "2012-05-23T08:01:01Z",
2016-06-02 11:05:42 +05:30
"is_admin": false,
2014-09-02 18:07:02 +05:30
"bio": null,
2016-06-02 11:05:42 +05:30
"location": null,
2014-09-02 18:07:02 +05:30
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
2016-11-03 12:29:30 +05:30
"organization": "",
2016-06-02 11:05:42 +05:30
"last_sign_in_at": null,
"confirmed_at": "2012-05-30T16:53:06.148Z",
2018-03-17 18:26:18 +05:30
"theme_id": 1,
2017-08-17 22:00:37 +05:30
"last_activity_on": "2012-05-23",
2014-09-02 18:07:02 +05:30
"color_scheme_id": 3,
2015-09-11 14:41:01 +05:30
"projects_limit": 100,
"current_sign_in_at": "2014-03-19T17:54:13Z",
2016-06-02 11:05:42 +05:30
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": true,
2018-11-18 11:00:15 +05:30
"external": false,
2019-09-04 21:01:54 +05:30
"private_profile": false
2014-09-02 18:07:02 +05:30
}
]
```
2019-09-30 21:07:59 +05:30
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"
...
}
]
```
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}
],
...
}
]
```
2018-11-18 11:00:15 +05:30
You can lookup users by external UID and provider:
2017-08-17 22:00:37 +05:30
```
GET /users?extern_uid=:extern_uid&provider=:provider
```
For example:
```
GET /users?extern_uid=1234567&provider=github
```
You can search for users who are external with: `/users?external=true`
2017-09-10 17:25:29 +05:30
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
```
2018-03-17 18:26:18 +05:30
You can filter by [custom attributes](custom_attributes.md) with:
```
GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```
2018-03-27 19:54:05 +05:30
You can include the users' [custom attributes](custom_attributes.md) in the response with:
```
GET /users?with_custom_attributes=true
```
2014-09-02 18:07:02 +05:30
## Single user
Get a single user.
### For user
```
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-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/john_smith",
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-06-02 11:05:42 +05:30
"location": null,
2018-12-05 23:21:45 +05:30
"public_email": "john@example.com",
"skype": "",
"linkedin": "",
"twitter": "",
2016-11-03 12:29:30 +05:30
"website_url": "",
"organization": ""
2014-09-02 18:07:02 +05:30
}
```
### For admin
```
GET /users/:id
```
Parameters:
- `id` (required) - The ID of a user
2019-09-30 21:07:59 +05:30
Example Responses:
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
2016-06-02 11:05:42 +05:30
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/john_smith",
2014-09-02 18:07:02 +05:30
"created_at": "2012-05-23T08:00:58Z",
2016-06-02 11:05:42 +05:30
"is_admin": false,
2014-09-02 18:07:02 +05:30
"bio": null,
2016-06-02 11:05:42 +05:30
"location": null,
2018-12-05 23:21:45 +05:30
"public_email": "john@example.com",
2014-09-02 18:07:02 +05:30
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
2016-11-03 12:29:30 +05:30
"organization": "",
2016-06-02 11:05:42 +05:30
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2018-03-17 18:26:18 +05:30
"theme_id": 1,
2017-08-17 22:00:37 +05:30
"last_activity_on": "2012-05-23",
2014-09-02 18:07:02 +05:30
"color_scheme_id": 2,
2016-06-02 11:05:42 +05:30
"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-09-02 18:07:02 +05:30
"can_create_group": true,
2015-04-26 12:48:37 +05:30
"can_create_project": true,
2016-06-02 11:05:42 +05:30
"two_factor_enabled": true,
2018-11-18 11:00:15 +05:30
"external": false,
2019-09-30 21:07:59 +05:30
"private_profile": false
}
```
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,
"username": "john_smith",
"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"
...
}
```
Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also
see the `group_saml` option:
```json
{
"id": 1,
"username": "john_smith",
"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"
"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}
],
...
2014-09-02 18:07:02 +05:30
}
```
2018-03-27 19:54:05 +05:30
You can include the user's [custom attributes](custom_attributes.md) in the response with:
```
GET /users/:id?with_custom_attributes=true
```
2014-09-02 18:07:02 +05:30
## User creation
2019-09-30 21:07:59 +05:30
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.
2014-09-02 18:07:02 +05:30
2019-10-12 21:52:04 +05:30
NOTE: **Note:**
From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29888/), `private_profile` will default to `false`.
2014-09-02 18:07:02 +05:30
```
POST /users
```
Parameters:
2017-09-10 17:25:29 +05:30
- `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
2018-12-05 23:21:45 +05:30
- `public_email` (optional) - The public email of the user
2017-09-10 17:25:29 +05:30
- `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-09-30 21:07:59 +05:30
- `external` (optional) - Flags the user as external - true or false (default)
2017-09-10 17:25:29 +05:30
- `avatar` (optional) - Image file for user's avatar
2019-09-30 21:07:59 +05:30
- `private_profile` (optional) - User's profile is private - true or false (default)
- `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)**
2014-09-02 18:07:02 +05:30
## User modification
Modifies an existing user. Only administrators can change attributes of a user.
```
PUT /users/:id
```
Parameters:
2018-12-05 23:21:45 +05:30
- `email` - Email
- `username` - Username
- `name` - Name
- `password` - Password
- `skype` - Skype ID
- `linkedin` - LinkedIn
- `twitter` - Twitter account
- `website_url` - Website URL
- `organization` - Organization name
- `projects_limit` - Limit projects each user can create
- `extern_uid` - External UID
- `provider` - External provider name
2019-09-30 21:07:59 +05:30
- `group_id_for_saml` (optional) - ID of group where SAML has been configured
2018-12-05 23:21:45 +05:30
- `bio` - 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
2018-03-17 18:26:18 +05:30
- `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)
2019-09-30 21:07:59 +05:30
- `external` (optional) - Flags the user as external - true or false (default)
- `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-12-05 23:21:45 +05:30
- `avatar` (optional) - Image file for user's avatar
2019-09-30 21:07:59 +05:30
- `private_profile` (optional) - User's profile is private - true or false (default)
- `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)**
- `note` (optional) - Admin notes for this user **(STARTER)**
2014-09-02 18:07:02 +05:30
2017-08-17 22:00:37 +05:30
On password update, user will be forced to change it upon next login.
Note, at the moment this method does only return a `404` error,
even in cases where a `409` (Conflict) would be more appropriate,
2014-09-02 18:07:02 +05:30
e.g. when renaming the email address to some existing one.
## User deletion
Deletes a user. Available only for administrators.
2018-03-17 18:26:18 +05:30
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
2014-09-02 18:07:02 +05:30
```
DELETE /users/:id
```
Parameters:
- `id` (required) - The ID of the user
2017-09-10 17:25:29 +05:30
- `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.
2014-09-02 18:07:02 +05:30
2019-09-30 21:07:59 +05:30
## List current user (for normal users)
2014-09-02 18:07:02 +05:30
Gets currently authenticated user.
```
GET /user
```
```json
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
2016-06-02 11:05:42 +05:30
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-11-03 12:29:30 +05:30
"web_url": "http://localhost:3000/john_smith",
2014-09-02 18:07:02 +05:30
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-06-02 11:05:42 +05:30
"location": null,
2018-12-05 23:21:45 +05:30
"public_email": "john@example.com",
2014-09-02 18:07:02 +05:30
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
2016-11-03 12:29:30 +05:30
"organization": "",
2016-06-02 11:05:42 +05:30
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2018-03-17 18:26:18 +05:30
"theme_id": 1,
2017-08-17 22:00:37 +05:30
"last_activity_on": "2012-05-23",
2014-09-02 18:07:02 +05:30
"color_scheme_id": 2,
2016-06-02 11:05:42 +05:30
"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-09-02 18:07:02 +05:30
"can_create_group": true,
2015-04-26 12:48:37 +05:30
"can_create_project": true,
2016-06-02 11:05:42 +05:30
"two_factor_enabled": true,
2018-11-18 11:00:15 +05:30
"external": false,
"private_profile": false
2014-09-02 18:07:02 +05:30
}
```
2019-09-30 21:07:59 +05:30
## List current user (for admins)
2017-01-15 13:20:01 +05:30
Parameters:
2017-09-10 17:25:29 +05:30
- `sudo` (optional) - the ID of a user to make the call in their place
2017-01-15 13:20:01 +05:30
```
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-12-05 23:21:45 +05:30
"public_email": "john@example.com",
2017-01-15 13:20:01 +05:30
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2018-03-17 18:26:18 +05:30
"theme_id": 1,
2017-08-17 22:00:37 +05:30
"last_activity_on": "2012-05-23",
2017-01-15 13:20:01 +05:30
"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-11-18 11:00:15 +05:30
"external": false,
"private_profile": false
}
```
## User status
Get the status of the currently signed in user.
```
GET /user/status
```
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status"
2018-11-18 11:00:15 +05:30
```
Example response:
```json
{
"emoji":"coffee",
"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>"
}
```
## Get the status of a user
Get the status of a user.
```
GET /users/:id_or_username/status
```
2019-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `id_or_username` | string | yes | The id or username of the user to get a status of |
2018-11-18 11:00:15 +05:30
```bash
curl "https://gitlab.example.com/users/janedoe/status"
```
Example response:
```json
{
"emoji":"coffee",
"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>"
}
```
## Set user status
Set the status of the current user.
```
PUT /user/status
```
2019-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
2018-11-18 11:00:15 +05:30
| `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][gemojione-index]. |
| `message` | string | no | The message to set as a status. It can also contain emoji codes. |
When both parameters `emoji` and `message` are empty, the status will be cleared.
```bash
2019-02-15 15:39:39 +05:30
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-11-18 11:00:15 +05:30
```
Example responses
```json
{
"emoji":"coffee",
"message":"I crave coffee",
"message_html": "I crave coffee"
2017-01-15 13:20:01 +05:30
}
```
2019-09-30 21:07:59 +05:30
## User counts
Get the counts (same as in top right menu) of the currently signed in user.
| 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-03-17 18:26:18 +05:30
## List user projects
2019-09-30 21:07:59 +05:30
Please refer to the [List of user projects](projects.md#list-user-projects).
2018-03-17 18:26:18 +05:30
2014-09-02 18:07:02 +05:30
## List SSH keys
Get a list of currently authenticated user's SSH keys.
```
GET /user/keys
```
```json
[
{
"id": 1,
"title": "Public key",
2015-04-26 12:48:37 +05:30
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2014-09-02 18:07:02 +05:30
},
{
"id": 3,
"title": "Another Public key",
2015-04-26 12:48:37 +05:30
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2014-09-02 18:07:02 +05:30
}
]
```
Parameters:
- **none**
## List SSH keys for user
2018-12-05 23:21:45 +05:30
Get a list of a specified user's SSH keys.
2014-09-02 18:07:02 +05:30
```
2017-08-17 22:00:37 +05:30
GET /users/:id/keys
2014-09-02 18:07:02 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
2014-09-02 18:07:02 +05:30
## Single SSH key
Get a single key.
```
2017-08-17 22:00:37 +05:30
GET /user/keys/:key_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `key_id` (required) - The ID of an SSH key
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
"title": "Public key",
2015-04-26 12:48:37 +05:30
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2014-09-02 18:07:02 +05:30
}
```
## Add SSH key
Creates a new key owned by the currently authenticated user.
```
POST /user/keys
```
Parameters:
- `title` (required) - new SSH Key's title
- `key` (required) - new SSH key
2015-04-26 12:48:37 +05:30
```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
}
```
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"
]
}
}
```
2014-09-02 18:07:02 +05:30
## Add SSH key for user
Create new key owned by specified user. Available only for admin
```
POST /users/:id/keys
```
Parameters:
- `id` (required) - id of specified user
- `title` (required) - new SSH Key's title
- `key` (required) - new SSH key
## Delete SSH key for current user
Deletes key owned by currently authenticated user.
2018-03-17 18:26:18 +05:30
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
2014-09-02 18:07:02 +05:30
```
2017-08-17 22:00:37 +05:30
DELETE /user/keys/:key_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `key_id` (required) - SSH key ID
2014-09-02 18:07:02 +05:30
## Delete SSH key for given user
Deletes key owned by a specified user. Available only for admin.
```
2017-08-17 22:00:37 +05:30
DELETE /users/:id/keys/:key_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
- `key_id` (required) - SSH key ID
2014-09-02 18:07:02 +05:30
2018-03-17 18:26:18 +05:30
## List all GPG keys
Get a list of currently authenticated user's GPG keys.
```
GET /user/gpg_keys
```
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `key_id` | integer | yes | The ID of the GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| key | string | yes | The new GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
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
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `key_id` | integer | yes | The ID of the GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
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
2018-03-17 18:26:18 +05:30
```
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-09-30 21:07:59 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ----------- |
| `id` | integer | yes | The ID of the user |
| `key_id` | integer | yes | The ID of the GPG key |
2018-03-17 18:26:18 +05:30
```bash
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
2018-03-17 18:26:18 +05:30
```
2015-09-11 14:41:01 +05:30
## 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
```
2017-08-17 22:00:37 +05:30
GET /users/:id/emails
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
2015-09-11 14:41:01 +05:30
## Single email
Get a single email.
```
2017-08-17 22:00:37 +05:30
GET /user/emails/:email_id
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `email_id` (required) - email ID
2015-09-11 14:41:01 +05:30
```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"
}
```
Will return created email with status `201 Created` on success. If an
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-12-05 23:21:45 +05:30
- `skip_confirmation` (optional) - Skip confirmation and assume e-mail is verified - true or false (default)
2015-09-11 14:41:01 +05:30
## Delete email for current user
Deletes email owned by currently authenticated user.
2018-03-17 18:26:18 +05:30
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
2015-09-11 14:41:01 +05:30
```
2017-08-17 22:00:37 +05:30
DELETE /user/emails/:email_id
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `email_id` (required) - email ID
2015-09-11 14:41:01 +05:30
## Delete email for given user
Deletes email owned by a specified user. Available only for admin.
```
2017-08-17 22:00:37 +05:30
DELETE /users/:id/emails/:email_id
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
- `email_id` (required) - email ID
2015-09-11 14:41:01 +05:30
## Block user
Blocks the specified user. Available only for admin.
```
2017-08-17 22:00:37 +05:30
POST /users/:id/block
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
2015-09-11 14:41:01 +05:30
2017-08-17 22:00:37 +05:30
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
2015-09-11 14:41:01 +05:30
## Unblock user
Unblocks the specified user. Available only for admin.
```
2017-08-17 22:00:37 +05:30
POST /users/:id/unblock
2015-09-11 14:41:01 +05:30
```
Parameters:
2017-08-17 22:00:37 +05:30
- `id` (required) - id of specified user
2015-09-11 14:41:01 +05:30
2017-08-17 22:00:37 +05:30
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
2016-11-03 12:29:30 +05:30
### Get user contribution events
2017-09-10 17:25:29 +05:30
Please refer to the [Events API documentation](events.md#get-user-contribution-events)
2016-11-03 12:29:30 +05:30
2017-08-17 22:00:37 +05:30
## Get all impersonation tokens of a user
> 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.
```
GET /users/:user_id/impersonation_tokens
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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-08-17 22:00:37 +05:30
```
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
2017-08-17 22:00:37 +05:30
```
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"
},
{
"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"
}
]
```
## Get an impersonation token of a user
> Requires admin permissions.
It shows a user's impersonation token.
```
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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-08-17 22:00:37 +05:30
```
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
2017-08-17 22:00:37 +05:30
```
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-12-05 23:21:45 +05:30
> Token values are returned once. Make sure you save it - you won't be able to access it again.
2017-08-17 22:00:37 +05:30
It creates a new impersonation token. Note that only administrators can do this.
You are only able to create impersonation tokens to impersonate the user and perform
2017-09-10 17:25:29 +05:30
both API calls and Git reads and writes. The user will not see these tokens in their profile
2017-08-17 22:00:37 +05:30
settings page.
```
POST /users/:user_id/impersonation_tokens
```
2019-09-30 21:07:59 +05:30
| 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-08-17 22:00:37 +05:30
```
2019-02-15 15:39:39 +05:30
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-08-17 22:00:37 +05:30
```
Example response:
```json
{
"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"
}
```
## Revoke an impersonation token
> Requires admin permissions.
It revokes an impersonation token.
```
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
```
```
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
2017-08-17 22:00:37 +05:30
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
### Get user activities (admin only)
2019-09-30 21:07:59 +05:30
NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
2017-08-17 22:00:37 +05:30
Get the last activity date for all users, sorted from oldest to newest.
The activities that update the timestamp are:
2019-09-30 21:07:59 +05:30
- Git HTTP/SSH activities (such as clone, push)
- User logging in into GitLab
- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8)
2017-08-17 22:00:37 +05:30
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
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/activities
2017-08-17 22:00:37 +05:30
```
Example response:
```json
[
{
"username": "user1",
"last_activity_on": "2015-12-14",
"last_activity_at": "2015-12-14"
},
{
"username": "user2",
"last_activity_on": "2015-12-15",
"last_activity_at": "2015-12-15"
},
{
"username": "user3",
"last_activity_on": "2015-12-16",
"last_activity_at": "2015-12-16"
}
]
```
Please note that `last_activity_at` is deprecated, please use `last_activity_on`.
2018-11-18 11:00:15 +05:30
[gemojione-index]: https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json