BigW Consortium Gitlab

users.md 24.6 KB
Newer Older
1
# Users API
2

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

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

36 37 38 39 40 41 42 43 44 45 46 47
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
```

Ciro Santilli committed
48
### For admins
49

50 51 52 53 54 55 56 57
```
GET /users
```

```json
[
  {
    "id": 1,
58
    "username": "john_smith",
59 60
    "email": "john@example.com",
    "name": "John Smith",
61
    "state": "active",
62
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
63
    "web_url": "http://localhost:3000/john_smith",
64 65
    "created_at": "2012-05-23T08:00:58Z",
    "bio": null,
66
    "location": null,
67 68 69
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert committed
70
    "website_url": "",
71
    "organization": "",
72 73
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
74
    "last_activity_on": "2012-05-23",
75
    "color_scheme_id": 2,
76 77 78 79 80 81 82
    "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"}
    ],
83
    "can_create_group": true,
84 85 86
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false
87 88 89
  },
  {
    "id": 2,
90
    "username": "jack_smith",
91 92
    "email": "jack@example.com",
    "name": "Jack Smith",
93
    "state": "blocked",
94
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
95
    "web_url": "http://localhost:3000/jack_smith",
96 97
    "created_at": "2012-05-23T08:01:01Z",
    "bio": null,
98
    "location": null,
99 100 101
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert committed
102
    "website_url": "",
103
    "organization": "",
104 105
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
106
    "last_activity_on": "2012-05-23",
107
    "color_scheme_id": 3,
108
    "projects_limit": 100,
109
    "current_sign_in_at": "2014-03-19T17:54:13Z",
110 111 112 113 114
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false
115 116 117 118
  }
]
```

Ciro Santilli committed
119
You can search for users by email or username with: `/users?search=John`
dosire committed
120

121 122 123 124 125 126 127 128 129 130 131
In addition, you can lookup users by username:

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

For example:

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

133 134 135 136 137 138 139 140 141 142 143 144
You can also lookup users by external UID and provider:

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

For example:

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

145 146
You can search for users who are external with: `/users?external=true`

147 148 149 150
## Single user

Get a single user.

Ciro Santilli committed
151
### For user
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

```
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",
168
  "web_url": "http://localhost:3000/john_smith",
169 170
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
171
  "location": null,
172 173 174
  "skype": "",
  "linkedin": "",
  "twitter": "",
175 176
  "website_url": "",
  "organization": ""
177 178 179
}
```

Ciro Santilli committed
180
### For admin
181

182 183 184 185 186 187
```
GET /users/:id
```

Parameters:

188
- `id` (required) - The ID of a user
189 190 191 192

```json
{
  "id": 1,
193
  "username": "john_smith",
194 195
  "email": "john@example.com",
  "name": "John Smith",
196
  "state": "active",
197
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
198
  "web_url": "http://localhost:3000/john_smith",
199 200
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
201
  "location": null,
202 203 204
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
205
  "website_url": "",
206
  "organization": "",
207 208
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
209
  "last_activity_on": "2012-05-23",
210
  "color_scheme_id": 2,
211 212 213 214 215 216 217
  "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"}
  ],
218
  "can_create_group": true,
219
  "can_create_project": true,
220 221
  "two_factor_enabled": true,
  "external": false
222 223 224
}
```

225
## User creation
226

227
Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority).
228 229 230 231 232 233 234

```
POST /users
```

Parameters:

235
- `email` (required)            - Email
236 237
- `password` (optional)         - Password
- `reset_password` (optional)   - Send user password reset link - true or false(default)
238 239 240
- `username` (required)         - Username
- `name` (required)             - Name
- `skype` (optional)            - Skype ID
Ciro Santilli committed
241
- `linkedin` (optional)         - LinkedIn
242
- `twitter` (optional)          - Twitter account
Ciro Santilli committed
243
- `website_url` (optional)      - Website URL
244
- `organization` (optional)     - Organization name
245 246 247
- `projects_limit` (optional)   - Number of projects user can create
- `extern_uid` (optional)       - External UID
- `provider` (optional)         - External provider name
Ciro Santilli committed
248
- `bio` (optional)              - User's biography
249
- `location` (optional)         - User's location
250 251
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
252
- `confirm` (optional)          - Require confirmation - true (default) or false
253
- `external` (optional)         - Flags the user as external - true or false(default)
254

255
## User modification
256 257

Modifies an existing user. Only administrators can change attributes of a user.
258 259 260 261 262 263

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

Parameters:
264

Ciro Santilli committed
265 266 267 268 269 270 271 272
- `email`                       - Email
- `username`                    - Username
- `name`                        - Name
- `password`                    - Password
- `skype`                       - Skype ID
- `linkedin`                    - LinkedIn
- `twitter`                     - Twitter account
- `website_url`                 - Website URL
273
- `organization`                - Organization name
Ciro Santilli committed
274 275 276 277
- `projects_limit`              - Limit projects each user can create
- `extern_uid`                  - External UID
- `provider`                    - External provider name
- `bio`                         - User's biography
278
- `location` (optional)         - User's location
Ciro Santilli committed
279 280
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
281
- `external` (optional)         - Flags the user as external - true or false(default)
Ciro Santilli committed
282

283
On password update, user will be forced to change it upon next login.
284 285
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 committed
286
e.g. when renaming the email address to some existing one.
287 288

## User deletion
289

Ciro Santilli committed
290 291
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
292
still returns a status code `200 OK`.
Ciro Santilli committed
293 294
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
295 296 297 298 299

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

300 301
Parameters:

302
- `id` (required) - The ID of the user
303

304 305 306
## User

### For normal users
307

308
Gets currently authenticated user.
309 310 311 312 313 314 315 316

```
GET /user
```

```json
{
  "id": 1,
317
  "username": "john_smith",
318 319
  "email": "john@example.com",
  "name": "John Smith",
320
  "state": "active",
321
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
322
  "web_url": "http://localhost:3000/john_smith",
323 324
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
325
  "location": null,
326 327 328
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
329
  "website_url": "",
330
  "organization": "",
331 332
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
333
  "last_activity_on": "2012-05-23",
334
  "color_scheme_id": 2,
335 336 337 338 339 340 341
  "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"}
  ],
342
  "can_create_group": true,
343
  "can_create_project": true,
344
  "two_factor_enabled": true,
345
  "external": false
346 347
}
```
348

349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378
### For admins

Parameters:

- `sudo` (required) - the ID of a user

```
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,
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "website_url": "",
  "organization": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
379
  "last_activity_on": "2012-05-23",
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395
  "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,
  "external": false,
  "private_token": "dd34asd13as"
}
```

396 397 398 399 400 401 402 403 404 405 406 407
## List SSH keys

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

```
GET /user/keys
```

```json
[
  {
    "id": 1,
408
    "title": "Public key",
409 410
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
411 412 413
  },
  {
    "id": 3,
414
    "title": "Another Public key",
415 416
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
417 418 419 420
  }
]
```

421 422
Parameters:

423
- **none**
424

425 426 427 428 429
## List SSH keys for user

Get a list of a specified user's SSH keys. Available only for admin

```
430
GET /users/:id/keys
431 432 433 434
```

Parameters:

435
- `id` (required) - id of specified user
436

437 438 439 440 441
## Single SSH key

Get a single key.

```
442
GET /user/keys/:key_id
443 444 445 446
```

Parameters:

447
- `key_id` (required) - The ID of an SSH key
448 449 450 451

```json
{
  "id": 1,
452
  "title": "Public key",
453 454
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
455 456
}
```
457

458 459
## Add SSH key

460
Creates a new key owned by the currently authenticated user.
461 462 463 464 465 466 467

```
POST /user/keys
```

Parameters:

468
- `title` (required) - new SSH Key's title
Ciro Santilli committed
469
- `key` (required)   - new SSH key
470

471 472 473 474 475 476 477 478 479
```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
}
```

480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
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"
    ]
  }
}
```

496 497 498 499 500 501 502 503 504 505
## Add SSH key for user

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

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

Parameters:

Ciro Santilli committed
506
- `id` (required)    - id of specified user
507
- `title` (required) - new SSH Key's title
Ciro Santilli committed
508
- `key` (required)   - new SSH key
509

510
## Delete SSH key for current user
511

Ciro Santilli committed
512 513
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
514
or not available results in `200 OK`.
515 516

```
517
DELETE /user/keys/:key_id
518 519 520 521
```

Parameters:

522
- `key_id` (required) - SSH key ID
523

524
## Delete SSH key for given user
525 526 527 528

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

```
529
DELETE /users/:id/keys/:key_id
530 531 532 533
```

Parameters:

534 535
- `id` (required) - id of specified user
- `key_id` (required)  - SSH key ID
536

537
Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
538

539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568
## 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

```
569
GET /users/:id/emails
570 571 572 573
```

Parameters:

574
- `id` (required) - id of specified user
575

Douwe Maan committed
576
## Single email
577

Douwe Maan committed
578
Get a single email.
579 580

```
581
GET /user/emails/:email_id
582 583 584 585
```

Parameters:

586
- `email_id` (required) - email ID
587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613

```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 committed
614
Will return created email with status `201 Created` on success. If an
615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646
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

## Delete email for current user

Deletes email owned by currently authenticated user.
This is an idempotent function and calling it on a email that is already deleted
or not available results in `200 OK`.

```
647
DELETE /user/emails/:email_id
648 649 650 651
```

Parameters:

652
- `email_id` (required) - email ID
653 654 655 656 657 658

## Delete email for given user

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

```
659
DELETE /users/:id/emails/:email_id
660 661 662 663
```

Parameters:

664 665
- `id` (required) - id of specified user
- `email_id` (required)  - email ID
666

Douwe Maan committed
667
Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
668

669 670 671 672 673
## Block user

Blocks the specified user.  Available only for admin.

```
674
POST /users/:id/block
675 676 677 678
```

Parameters:

679
- `id` (required) - id of specified user
680

681
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
682
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
683 684 685 686 687 688

## Unblock user

Unblocks the specified user.  Available only for admin.

```
689
POST /users/:id/unblock
690 691 692 693
```

Parameters:

694
- `id` (required) - id of specified user
695

696
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
697
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
698 699 700

### Get user contribution events

701
Get the contribution events for the specified user, sorted from newest to oldest.
702 703 704 705 706 707 708 709 710 711 712 713

```
GET /users/:id/events
```

Parameters:

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

```bash
714
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/:id/events
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735
```

Example response:

```json
[
  {
    "title": null,
    "project_id": 15,
    "action_name": "closed",
    "target_id": 830,
    "target_type": "Issue",
    "author_id": 1,
    "data": null,
    "target_title": "Public project search field",
    "author": {
      "name": "Dmitriy Zaporozhets",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
736
      "web_url": "http://localhost:3000/root"
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752
    },
    "author_username": "root"
  },
  {
    "title": null,
    "project_id": 15,
    "action_name": "opened",
    "target_id": null,
    "target_type": null,
    "author_id": 1,
    "author": {
      "name": "Dmitriy Zaporozhets",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
753
      "web_url": "http://localhost:3000/root"
754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
    },
    "author_username": "john",
    "data": {
      "before": "50d4420237a9de7be1304607147aec22e4a14af7",
      "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "ref": "refs/heads/master",
      "user_id": 1,
      "user_name": "Dmitriy Zaporozhets",
      "repository": {
        "name": "gitlabhq",
        "url": "git@dev.gitlab.org:gitlab/gitlabhq.git",
        "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.",
        "homepage": "https://dev.gitlab.org/gitlab/gitlabhq"
      },
      "commits": [
        {
          "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
          "message": "Add simple search to projects in public area",
          "timestamp": "2013-05-13T18:18:08+00:00",
          "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428",
          "author": {
            "name": "Dmitriy Zaporozhets",
            "email": "dmitriy.zaporozhets@gmail.com"
          }
        }
      ],
      "total_commits_count": 1
    },
    "target_title": null
  },
  {
    "title": null,
    "project_id": 15,
    "action_name": "closed",
    "target_id": 840,
    "target_type": "Issue",
    "author_id": 1,
    "data": null,
    "target_title": "Finish & merge Code search PR",
    "author": {
      "name": "Dmitriy Zaporozhets",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
799
      "web_url": "http://localhost:3000/root"
800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
    },
    "author_username": "root"
  },
  {
    "title": null,
    "project_id": 15,
    "action_name": "commented on",
    "target_id": 1312,
    "target_type": "Note",
    "author_id": 1,
    "data": null,
    "target_title": null,
    "created_at": "2015-12-04T10:33:58.089Z",
    "note": {
      "id": 1312,
      "body": "What an awesome day!",
      "attachment": null,
      "author": {
        "name": "Dmitriy Zaporozhets",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
823
        "web_url": "http://localhost:3000/root"
824 825 826 827 828 829 830 831 832 833 834 835
      },
      "created_at": "2015-12-04T10:33:56.698Z",
      "system": false,
      "noteable_id": 377,
      "noteable_type": "Issue"
    },
    "author": {
      "name": "Dmitriy Zaporozhets",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
836
      "web_url": "http://localhost:3000/root"
837 838 839 840 841
    },
    "author_username": "root"
  }
]
```
842

843
## Get all impersonation tokens of a user
844

845 846 847 848
> 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.
849 850

```
851
GET /users/:user_id/impersonation_tokens
852 853 854 855 856 857
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
858
| `user_id` | integer | yes | The ID of the user |
859 860 861 862 863
| `state`   | string  | no | filter tokens based on state (`all`, `active`, `inactive`) |

```
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
```
864

865
Example response:
866

867 868
```json
[
869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894
   {
      "active" : true,
      "token" : "EsMo-vhKfXGwX9RKrwiy",
      "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,
      "token" : "ZcZRpLeEuQRprkRjYydY",
      "name" : "mytoken2",
      "created_at" : "2017-03-17T17:19:28.697Z",
      "id" : 3,
      "impersonation" : true,
      "expires_at" : "2017-04-14"
   }
895 896 897
]
```

898
## Get an impersonation token of a user
899

900 901 902
> Requires admin permissions.

It shows a user's impersonation token.
903 904

```
905
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
906 907 908 909 910 911
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
912 913
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
914

915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939
```
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
```

Example response:

```json
{
   "active" : true,
   "token" : "EsMo-vhKfXGwX9RKrwiy",
   "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.
940

941
It creates a new impersonation token. Note that only administrators can do this.
942 943 944
You are only able to create impersonation tokens to impersonate the user and perform
both API calls and Git reads and writes. The user will not see these tokens in his profile
settings page.
945 946

```
947
POST /users/:user_id/impersonation_tokens
948 949 950 951 952 953
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
954
| `user_id` | integer | yes | The ID of the user |
955 956 957 958 959 960 961
| `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`) |

```
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
```
962

963
Example response:
964

965 966
```json
{
967 968 969 970 971 972 973 974 975 976 977
   "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"
978 979
}
```
980

981 982
## Revoke an impersonation token

983 984 985
> Requires admin permissions.

It revokes an impersonation token.
986 987

```
988
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
989 990
```

991 992 993 994
```
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
```

995 996 997 998
Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
999 1000
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026

### 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

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
1027
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities
1028 1029 1030 1031 1032 1033 1034 1035
```

Example response:

```json
[
  {
    "username": "user1",
1036 1037
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
1038 1039 1040
  },
  {
    "username": "user2",
1041 1042
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
1043 1044 1045
  },
  {
    "username": "user3",
1046 1047
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
1048 1049
  }
]
1050 1051 1052
```

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