users.md 34.9 KB
Newer Older
1
# Users API
Marin Jankovski's avatar
Marin Jankovski committed
2

Nihad Abbasov's avatar
Nihad Abbasov committed
3 4 5
## List users

Get a list of users.
6

7
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
Nihad Abbasov's avatar
Nihad Abbasov committed
8

Ciro Santilli's avatar
Ciro Santilli committed
9
### For normal users
10 11 12 13 14 15 16 17 18 19 20 21 22

```
GET /users
```

```json
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
23
    "web_url": "http://localhost:3000/john_smith"
24 25 26 27 28 29 30
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
31
    "web_url": "http://localhost:3000/jack_smith"
32 33 34 35
  }
]
```

Daniel Fernau's avatar
Daniel Fernau committed
36 37 38 39 40 41 42 43 44 45 46 47 48 49
You can also search for users by email or username with: `/users?search=John`

In addition, you can lookup users by username:

```
GET /users?username=:username
```

For example:

```
GET /users?username=jack_smith
```

50 51 52 53 54 55 56 57 58 59 60 61
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
```

62 63 64
NOTE: **Note:**
Username search is case insensitive.

Ciro Santilli's avatar
Ciro Santilli committed
65
### For admins
66

Nihad Abbasov's avatar
Nihad Abbasov committed
67 68 69 70
```
GET /users
```

71 72
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
73 74
| `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` |
75
| `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
76

Nihad Abbasov's avatar
Nihad Abbasov committed
77 78 79 80
```json
[
  {
    "id": 1,
81
    "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
82 83
    "email": "john@example.com",
    "name": "John Smith",
84
    "state": "active",
85
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
86
    "web_url": "http://localhost:3000/john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
87
    "created_at": "2012-05-23T08:00:58Z",
88
    "is_admin": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
89
    "bio": null,
90
    "location": null,
Nihad Abbasov's avatar
Nihad Abbasov committed
91 92 93
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
94
    "website_url": "",
95
    "organization": "",
96 97
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
98
    "theme_id": 1,
99
    "last_activity_on": "2012-05-23",
100
    "color_scheme_id": 2,
101 102 103 104 105 106 107
    "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"}
    ],
108
    "can_create_group": true,
109 110
    "can_create_project": true,
    "two_factor_enabled": true,
111 112
    "external": false,
    "private_profile": false
Nihad Abbasov's avatar
Nihad Abbasov committed
113 114 115
  },
  {
    "id": 2,
116
    "username": "jack_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
117 118
    "email": "jack@example.com",
    "name": "Jack Smith",
119
    "state": "blocked",
120
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
121
    "web_url": "http://localhost:3000/jack_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
122
    "created_at": "2012-05-23T08:01:01Z",
123
    "is_admin": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
124
    "bio": null,
125
    "location": null,
Nihad Abbasov's avatar
Nihad Abbasov committed
126 127 128
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
129
    "website_url": "",
130
    "organization": "",
131 132
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
133
    "theme_id": 1,
134
    "last_activity_on": "2012-05-23",
135
    "color_scheme_id": 3,
136
    "projects_limit": 100,
Stan Hu's avatar
Stan Hu committed
137
    "current_sign_in_at": "2014-03-19T17:54:13Z",
138 139 140 141
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
142 143
    "external": false,
    "private_profile": false
Nihad Abbasov's avatar
Nihad Abbasov committed
144 145 146 147
  }
]
```

Daniel Fernau's avatar
Daniel Fernau committed
148
You can lookup users by external UID and provider:
149 150 151 152 153 154 155 156 157 158 159

```
GET /users?extern_uid=:extern_uid&provider=:provider
```

For example:

```
GET /users?extern_uid=1234567&provider=github
```

160 161
You can search for users who are external with: `/users?external=true`

162 163 164 165 166 167
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
```

168 169 170 171 172 173
You can filter by [custom attributes](custom_attributes.md) with:

```
GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

174 175 176 177 178 179
You can include the users' [custom attributes](custom_attributes.md) in the response with:

```
GET /users?with_custom_attributes=true
```

Nihad Abbasov's avatar
Nihad Abbasov committed
180 181 182 183
## Single user

Get a single user.

Ciro Santilli's avatar
Ciro Santilli committed
184
### For user
185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200

```
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",
201
  "web_url": "http://localhost:3000/john_smith",
202 203
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
204
  "location": null,
205
  "public_email": "john@example.com",
206 207 208
  "skype": "",
  "linkedin": "",
  "twitter": "",
209 210
  "website_url": "",
  "organization": ""
211 212 213
}
```

Ciro Santilli's avatar
Ciro Santilli committed
214
### For admin
215

Nihad Abbasov's avatar
Nihad Abbasov committed
216 217 218 219 220 221
```
GET /users/:id
```

Parameters:

222
- `id` (required) - The ID of a user
Nihad Abbasov's avatar
Nihad Abbasov committed
223 224 225 226

```json
{
  "id": 1,
227
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
228 229
  "email": "john@example.com",
  "name": "John Smith",
230
  "state": "active",
231
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
232
  "web_url": "http://localhost:3000/john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
233
  "created_at": "2012-05-23T08:00:58Z",
234
  "is_admin": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
235
  "bio": null,
236
  "location": null,
237
  "public_email": "john@example.com",
Nihad Abbasov's avatar
Nihad Abbasov committed
238 239 240
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
241
  "website_url": "",
242
  "organization": "",
243 244
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
245
  "theme_id": 1,
246
  "last_activity_on": "2012-05-23",
247
  "color_scheme_id": 2,
248 249 250 251 252 253 254
  "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"}
  ],
255
  "can_create_group": true,
256
  "can_create_project": true,
257
  "two_factor_enabled": true,
258 259
  "external": false,
  "private_profile": false
Nihad Abbasov's avatar
Nihad Abbasov committed
260 261 262
}
```

263 264 265 266 267 268
You can include the user's [custom attributes](custom_attributes.md) in the response with:

```
GET /users/:id?with_custom_attributes=true
```

269
## User creation
270

271
Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority). If `reset_password` is `false`, then `password` is required.
272 273 274 275 276 277 278

```
POST /users
```

Parameters:

279 280 281 282 283 284 285 286 287 288 289 290 291 292 293
- `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
294
- `public_email` (optional)      - The public email of the user
295 296 297 298 299
- `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)
- `external` (optional)          - Flags the user as external - true or false(default)
- `avatar` (optional)            - Image file for user's avatar
Lin Jen-Shin's avatar
Lin Jen-Shin committed
300
- `private_profile` (optional)   - User's profile is private - true or false
301

302
## User modification
303 304

Modifies an existing user. Only administrators can change attributes of a user.
305 306 307 308 309 310

```
PUT /users/:id
```

Parameters:
311

312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
- `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
- `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
Daniel Juarez's avatar
Daniel Juarez committed
329
- `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)
330 331 332
- `external` (optional)            - Flags the user as external - true or false(default)
- `avatar` (optional)              - Image file for user's avatar
- `private_profile` (optional)     - User's profile is private - true or false
Ciro Santilli's avatar
Ciro Santilli committed
333

334
On password update, user will be forced to change it upon next login.
335 336
Note, at the moment this method does only return a `404` error,
even in cases where a `409` (Conflict) would be more appropriate,
Ciro Santilli's avatar
Ciro Santilli committed
337
e.g. when renaming the email address to some existing one.
338 339

## User deletion
340

Ciro Santilli's avatar
Ciro Santilli committed
341
Deletes a user. Available only for administrators.
342
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
343 344 345 346 347

```
DELETE /users/:id
```

348 349
Parameters:

350
- `id` (required) - The ID of the user
351 352 353
- `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.
354

355 356 357
## User

### For normal users
Nihad Abbasov's avatar
Nihad Abbasov committed
358

359
Gets currently authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
360 361 362 363 364 365 366 367

```
GET /user
```

```json
{
  "id": 1,
368
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
369 370
  "email": "john@example.com",
  "name": "John Smith",
371
  "state": "active",
372
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
373
  "web_url": "http://localhost:3000/john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
374 375
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
376
  "location": null,
377
  "public_email": "john@example.com",
Nihad Abbasov's avatar
Nihad Abbasov committed
378 379 380
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
381
  "website_url": "",
382
  "organization": "",
383 384
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
385
  "theme_id": 1,
386
  "last_activity_on": "2012-05-23",
387
  "color_scheme_id": 2,
388 389 390 391 392 393 394
  "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"}
  ],
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
395
  "can_create_group": true,
396
  "can_create_project": true,
397
  "two_factor_enabled": true,
398 399
  "external": false,
  "private_profile": false
Nihad Abbasov's avatar
Nihad Abbasov committed
400 401
}
```
402

403 404 405 406
### For admins

Parameters:

407
- `sudo` (optional) - the ID of a user to make the call in their place
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425

```
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,
426
  "public_email": "john@example.com",
427 428 429 430 431 432 433
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "website_url": "",
  "organization": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
434
  "theme_id": 1,
435
  "last_activity_on": "2012-05-23",
436 437 438 439 440 441 442 443 444 445 446
  "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,
447 448
  "external": false,
  "private_profile": false
449 450 451
}
```

452 453 454 455 456 457 458 459
## User status

Get the status of the currently signed in user.

```
GET /user/status
```

460
```bash
461
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status"
462 463 464 465
```

Example response:

466 467 468
```json
{
  "emoji":"coffee",
469 470
  "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>"
471 472 473 474 475 476 477 478 479 480 481
}
```

## Get the status of a user

Get the status of a user.

```
GET /users/:id_or_username/status
```

482 483 484 485 486 487 488 489 490 491
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id_or_username` | string | yes    | The id or username of the user to get a status of |

```bash
curl "https://gitlab.example.com/users/janedoe/status"
```

Example response:

492 493 494
```json
{
  "emoji":"coffee",
495 496
  "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>"
497 498 499 500 501 502 503 504 505 506 507 508 509 510
}
```

## Set user status

Set the status of the current user.

```
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][gemojione-index]. |
511
| `message` | string | no     | The message to set as a status. It can also contain emoji codes. |
512

513 514 515
When both parameters `emoji` and `message` are empty, the status will be cleared.

```bash
516
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
517 518 519 520 521 522 523 524 525 526 527
```

Example responses

```json
{
  "emoji":"coffee",
  "message":"I crave coffee",
  "message_html": "I crave coffee"
}
```
528

529 530 531 532
## List user projects

Please refer to the [List of user projects ](projects.md#list-user-projects).

533 534 535 536 537 538 539 540 541 542 543 544
## List SSH keys

Get a list of currently authenticated user's SSH keys.

```
GET /user/keys
```

```json
[
  {
    "id": 1,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
545
    "title": "Public key",
546 547
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
548 549 550
  },
  {
    "id": 3,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
551
    "title": "Another Public key",
552 553
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
554 555 556 557
  }
]
```

558 559
Parameters:

560
- **none**
561

562 563
## List SSH keys for user

564
Get a list of a specified user's SSH keys.
565 566

```
Robert Schilling's avatar
Robert Schilling committed
567
GET /users/:id/keys
568 569 570 571
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
572
- `id` (required) - id of specified user
573

574 575 576 577 578
## Single SSH key

Get a single key.

```
Robert Schilling's avatar
Robert Schilling committed
579
GET /user/keys/:key_id
580 581 582 583
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
584
- `key_id` (required) - The ID of an SSH key
585 586 587 588

```json
{
  "id": 1,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
589
  "title": "Public key",
590 591
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
592 593
}
```
594

595 596
## Add SSH key

597
Creates a new key owned by the currently authenticated user.
598 599 600 601 602 603 604

```
POST /user/keys
```

Parameters:

605
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
606
- `key` (required)   - new SSH key
607

608 609 610 611 612 613 614 615 616
```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
}
```

617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632
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"
    ]
  }
}
```

633 634 635 636 637 638 639 640 641 642
## Add SSH key for user

Create new key owned by specified user. Available only for admin

```
POST /users/:id/keys
```

Parameters:

Ciro Santilli's avatar
Ciro Santilli committed
643
- `id` (required)    - id of specified user
644
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
645
- `key` (required)   - new SSH key
646

647
## Delete SSH key for current user
648

Ciro Santilli's avatar
Ciro Santilli committed
649
Deletes key owned by currently authenticated user.
650
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
651 652

```
Robert Schilling's avatar
Robert Schilling committed
653
DELETE /user/keys/:key_id
654 655 656 657
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
658
- `key_id` (required) - SSH key ID
659

660
## Delete SSH key for given user
661 662 663 664

Deletes key owned by a specified user. Available only for admin.

```
Robert Schilling's avatar
Robert Schilling committed
665
DELETE /users/:id/keys/:key_id
666 667 668 669
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
670 671
- `id` (required) - id of specified user
- `key_id` (required)  - SSH key ID
672

Robert Schilling's avatar
Robert Schilling committed
673 674 675 676 677 678 679 680 681
## List all GPG keys

Get a list of currently authenticated user's GPG keys.

```
GET /user/gpg_keys
```

```bash
682
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys
Robert Schilling's avatar
Robert Schilling committed
683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `key_id`  | integer | yes   | The ID of the GPG key |

```bash
712
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
Robert Schilling's avatar
Robert Schilling committed
713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| key       | string | yes    | The new GPG key |

```bash
740
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
Robert Schilling's avatar
Robert Schilling committed
741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `key_id`  | integer | yes   | The ID of the GPG key |

```bash
770
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
Robert Schilling's avatar
Robert Schilling committed
771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes   | The ID of the user |

```bash
790
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
Robert Schilling's avatar
Robert Schilling committed
791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes   | The ID of the user |
| `key_id`  | integer | yes   | The ID of the GPG key |

```bash
821
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
Robert Schilling's avatar
Robert Schilling committed
822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes   | The ID of the user |
| `key_id`  | integer | yes   | The ID of the GPG key |

```bash
850
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
Robert Schilling's avatar
Robert Schilling committed
851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880
```

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:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | integer | yes   | The ID of the user |
| `key_id`  | integer | yes   | The ID of the GPG key |

```bash
881
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
Robert Schilling's avatar
Robert Schilling committed
882 883
```

884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913
## 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

```
Robert Schilling's avatar
Robert Schilling committed
914
GET /users/:id/emails
915 916 917 918
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
919
- `id` (required) - id of specified user
920

Douwe Maan's avatar
Douwe Maan committed
921
## Single email
922

Douwe Maan's avatar
Douwe Maan committed
923
Get a single email.
924 925

```
Robert Schilling's avatar
Robert Schilling committed
926
GET /user/emails/:email_id
927 928 929 930
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
931
- `email_id` (required) - email ID
932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958

```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"
}
```

Douwe Maan's avatar
Douwe Maan committed
959
Will return created email with status `201 Created` on success. If an
960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983
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
984
- `skip_confirmation` (optional) - Skip confirmation and assume e-mail is verified - true or false (default)
985 986 987 988

## Delete email for current user

Deletes email owned by currently authenticated user.
989
This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
990 991

```
Robert Schilling's avatar
Robert Schilling committed
992
DELETE /user/emails/:email_id
993 994 995 996
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
997
- `email_id` (required) - email ID
998 999 1000 1001 1002 1003

## Delete email for given user

Deletes email owned by a specified user. Available only for admin.

```
Robert Schilling's avatar
Robert Schilling committed
1004
DELETE /users/:id/emails/:email_id
1005 1006 1007 1008
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
1009 1010
- `id` (required) - id of specified user
- `email_id` (required)  - email ID
1011

1012 1013 1014 1015 1016
## Block user

Blocks the specified user.  Available only for admin.

```
1017
POST /users/:id/block
1018 1019 1020 1021
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
1022
- `id` (required) - id of specified user
1023

1024
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
1025
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
1026 1027 1028 1029 1030 1031

## Unblock user

Unblocks the specified user.  Available only for admin.

```
1032
POST /users/:id/unblock
1033 1034 1035 1036
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
1037
- `id` (required) - id of specified user
1038

1039
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
1040
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
1041 1042 1043

### Get user contribution events

Mark Fletcher's avatar
Mark Fletcher committed
1044
Please refer to the [Events API documentation](events.md#get-user-contribution-events)
1045

1046
## Get all impersonation tokens of a user
1047

1048 1049 1050 1051
> 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.
1052 1053

```
1054
GET /users/:user_id/impersonation_tokens
1055 1056 1057 1058 1059 1060
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1061
| `user_id` | integer | yes | The ID of the user |
1062 1063 1064
| `state`   | string  | no | filter tokens based on state (`all`, `active`, `inactive`) |

```
1065
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
1066
```
1067

1068
Example response:
1069

1070 1071
```json
[
1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095
   {
      "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"
   }
1096 1097 1098
]
```

1099
## Get an impersonation token of a user
1100

1101 1102 1103
> Requires admin permissions.

It shows a user's impersonation token.
1104 1105

```
1106
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
1107 1108 1109 1110 1111 1112
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1113 1114
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
1115

1116
```
1117
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139
```

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.
1140

1141 1142
> Token values are returned once. Make sure you save it - you won't be able to access it again.

1143
It creates a new impersonation token. Note that only administrators can do this.
1144
You are only able to create impersonation tokens to impersonate the user and perform
1145
both API calls and Git reads and writes. The user will not see these tokens in their profile
1146
settings page.
1147 1148

```
1149
POST /users/:user_id/impersonation_tokens
1150 1151 1152 1153 1154 1155
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1156
| `user_id` | integer | yes | The ID of the user |
1157 1158 1159 1160 1161
| `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`) |

```
1162
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
1163
```
1164

1165
Example response:
1166

1167 1168
```json
{
1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179
   "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"
1180 1181
}
```
1182

1183 1184
## Revoke an impersonation token

1185 1186 1187
> Requires admin permissions.

It revokes an impersonation token.
1188 1189

```
1190
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
1191 1192
```

1193
```
1194
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
1195 1196
```

1197 1198 1199 1200
Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
1201 1202
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213

### Get user activities (admin only)

>**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.

Get the last activity date for all users, sorted from oldest to newest.

The activities that update the timestamp are:

  - Git HTTP/SSH activities (such as clone, push)
  - User logging in into GitLab
1214
  - 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)
1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229

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
1230
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/activities
1231 1232 1233 1234 1235 1236 1237 1238
```

Example response:

```json
[
  {
    "username": "user1",
1239 1240
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
1241 1242 1243
  },
  {
    "username": "user2",
1244 1245
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
1246 1247 1248
  },
  {
    "username": "user3",
1249 1250
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
1251 1252
  }
]
1253 1254 1255
```

Please note that `last_activity_at` is deprecated, please use `last_activity_on`.
1256 1257

[gemojione-index]: https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json