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

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

5 6
Active users = Total accounts - Blocked users

Nihad Abbasov's avatar
Nihad Abbasov committed
7
Get a list of users.
8

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

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

```
GET /users
```

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

38 39 40 41 42 43 44 45 46 47 48 49
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's avatar
Ciro Santilli committed
50
### For admins
51

Nihad Abbasov's avatar
Nihad Abbasov committed
52 53 54 55 56 57 58 59
```
GET /users
```

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

Ciro Santilli's avatar
Typo.  
Ciro Santilli committed
123
You can search for users by email or username with: `/users?search=John`
dosire's avatar
dosire committed
124

125 126 127 128 129 130 131 132 133 134 135
In addition, you can lookup users by username:

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

For example:

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

137 138 139 140 141 142 143 144 145 146 147 148
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
```

149 150
You can search for users who are external with: `/users?external=true`

151 152 153 154 155 156
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
```

Nihad Abbasov's avatar
Nihad Abbasov committed
157 158 159 160
## Single user

Get a single user.

Ciro Santilli's avatar
Ciro Santilli committed
161
### For user
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177

```
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",
178
  "web_url": "http://localhost:3000/john_smith",
179 180
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
181
  "location": null,
182 183 184
  "skype": "",
  "linkedin": "",
  "twitter": "",
185 186
  "website_url": "",
  "organization": ""
187 188 189
}
```

Ciro Santilli's avatar
Ciro Santilli committed
190
### For admin
191

Nihad Abbasov's avatar
Nihad Abbasov committed
192 193 194 195 196 197
```
GET /users/:id
```

Parameters:

198
- `id` (required) - The ID of a user
Nihad Abbasov's avatar
Nihad Abbasov committed
199 200 201 202

```json
{
  "id": 1,
203
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
204 205
  "email": "john@example.com",
  "name": "John Smith",
206
  "state": "active",
207
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
208
  "web_url": "http://localhost:3000/john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
209
  "created_at": "2012-05-23T08:00:58Z",
210
  "is_admin": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
211
  "bio": null,
212
  "location": null,
Nihad Abbasov's avatar
Nihad Abbasov committed
213 214 215
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
216
  "website_url": "",
217
  "organization": "",
218 219
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
220
  "last_activity_on": "2012-05-23",
221
  "color_scheme_id": 2,
222 223 224 225 226 227 228
  "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"}
  ],
229
  "can_create_group": true,
230
  "can_create_project": true,
231
  "two_factor_enabled": true,
232 233
  "external": false,
  "shared_runners_minutes_limit": 133
Nihad Abbasov's avatar
Nihad Abbasov committed
234 235 236
}
```

237
## User creation
238

239
Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority).
240 241 242 243 244 245 246

```
POST /users
```

Parameters:

247
- `email` (required)            - Email
248 249
- `password` (optional)         - Password
- `reset_password` (optional)   - Send user password reset link - true or false(default)
250 251 252
- `username` (required)         - Username
- `name` (required)             - Name
- `skype` (optional)            - Skype ID
Ciro Santilli's avatar
Ciro Santilli committed
253
- `linkedin` (optional)         - LinkedIn
254
- `twitter` (optional)          - Twitter account
Ciro Santilli's avatar
Ciro Santilli committed
255
- `website_url` (optional)      - Website URL
256
- `organization` (optional)     - Organization name
257 258 259
- `projects_limit` (optional)   - Number of projects user can create
- `extern_uid` (optional)       - External UID
- `provider` (optional)         - External provider name
Ciro Santilli's avatar
Ciro Santilli committed
260
- `bio` (optional)              - User's biography
261
- `location` (optional)         - User's location
262 263
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
264
- `confirm` (optional)          - Require confirmation - true (default) or false
265
- `external` (optional)         - Flags the user as external - true or false(default)
266
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
267
- `avatar` (optional)           - Image file for user's avatar
268

269
## User modification
270 271

Modifies an existing user. Only administrators can change attributes of a user.
272 273 274 275 276 277

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

Parameters:
278

Ciro Santilli's avatar
Ciro Santilli committed
279 280 281 282 283 284 285 286
- `email`                       - Email
- `username`                    - Username
- `name`                        - Name
- `password`                    - Password
- `skype`                       - Skype ID
- `linkedin`                    - LinkedIn
- `twitter`                     - Twitter account
- `website_url`                 - Website URL
287
- `organization`                - Organization name
Ciro Santilli's avatar
Ciro Santilli committed
288 289 290 291
- `projects_limit`              - Limit projects each user can create
- `extern_uid`                  - External UID
- `provider`                    - External provider name
- `bio`                         - User's biography
292
- `location` (optional)         - User's location
Ciro Santilli's avatar
Ciro Santilli committed
293 294
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
295
- `external` (optional)         - Flags the user as external - true or false(default)
296
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
297
- `avatar` (optional)           - Image file for user's avatar
Ciro Santilli's avatar
Ciro Santilli committed
298

299
On password update, user will be forced to change it upon next login.
300 301
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
302
e.g. when renaming the email address to some existing one.
303 304

## User deletion
305

Ciro Santilli's avatar
Ciro Santilli committed
306 307
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
308
still returns a status code `200 OK`.
Ciro Santilli's avatar
Ciro Santilli committed
309 310
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
311 312 313 314 315

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

316 317
Parameters:

318
- `id` (required) - The ID of the user
319 320 321
- `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.
322

323 324 325
## User

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

327
Gets currently authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
328 329 330 331 332 333 334 335

```
GET /user
```

```json
{
  "id": 1,
336
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
337 338
  "email": "john@example.com",
  "name": "John Smith",
339
  "state": "active",
340
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
341
  "web_url": "http://localhost:3000/john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
342 343
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
344
  "location": null,
Nihad Abbasov's avatar
Nihad Abbasov committed
345 346 347
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
348
  "website_url": "",
349
  "organization": "",
350 351
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
352
  "last_activity_on": "2012-05-23",
353
  "color_scheme_id": 2,
354 355 356 357 358 359 360
  "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
361
  "can_create_group": true,
362
  "can_create_project": true,
363
  "two_factor_enabled": true,
364
  "external": false
Nihad Abbasov's avatar
Nihad Abbasov committed
365 366
}
```
367

368 369 370 371
### For admins

Parameters:

372
- `sudo` (optional) - the ID of a user to make the call in their place
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397

```
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",
398
  "last_activity_on": "2012-05-23",
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
  "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"
}
```

415 416 417 418 419 420 421 422 423 424 425 426
## 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
427
    "title": "Public key",
428 429
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
430 431 432
  },
  {
    "id": 3,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
433
    "title": "Another Public key",
434 435
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
436 437 438 439
  }
]
```

440 441
Parameters:

442
- **none**
443

444 445 446 447 448
## List SSH keys for user

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

```
Robert Schilling's avatar
Robert Schilling committed
449
GET /users/:id/keys
450 451 452 453
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
454
- `id` (required) - id of specified user
455

456 457 458 459 460
## Single SSH key

Get a single key.

```
Robert Schilling's avatar
Robert Schilling committed
461
GET /user/keys/:key_id
462 463 464 465
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
466
- `key_id` (required) - The ID of an SSH key
467 468 469 470

```json
{
  "id": 1,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
471
  "title": "Public key",
472 473
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
474 475
}
```
476

477 478
## Add SSH key

479
Creates a new key owned by the currently authenticated user.
480 481 482 483 484 485 486

```
POST /user/keys
```

Parameters:

487
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
488
- `key` (required)   - new SSH key
489

490 491 492 493 494 495 496 497 498
```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
}
```

499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514
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"
    ]
  }
}
```

515 516 517 518 519 520 521 522 523 524
## 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
525
- `id` (required)    - id of specified user
526
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
527
- `key` (required)   - new SSH key
528

529
## Delete SSH key for current user
530

Ciro Santilli's avatar
Ciro Santilli committed
531 532
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
533
or not available results in `200 OK`.
534 535

```
Robert Schilling's avatar
Robert Schilling committed
536
DELETE /user/keys/:key_id
537 538 539 540
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
541
- `key_id` (required) - SSH key ID
542

543
## Delete SSH key for given user
544 545 546 547

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

```
Robert Schilling's avatar
Robert Schilling committed
548
DELETE /users/:id/keys/:key_id
549 550 551 552
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
553 554
- `id` (required) - id of specified user
- `key_id` (required)  - SSH key ID
555

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

558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587
## 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
588
GET /users/:id/emails
589 590 591 592
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
593
- `id` (required) - id of specified user
594

Douwe Maan's avatar
Douwe Maan committed
595
## Single email
596

Douwe Maan's avatar
Douwe Maan committed
597
Get a single email.
598 599

```
Robert Schilling's avatar
Robert Schilling committed
600
GET /user/emails/:email_id
601 602 603 604
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
605
- `email_id` (required) - email ID
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632

```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
633
Will return created email with status `201 Created` on success. If an
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665
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`.

```
Robert Schilling's avatar
Robert Schilling committed
666
DELETE /user/emails/:email_id
667 668 669 670
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
671
- `email_id` (required) - email ID
672 673 674 675 676 677

## Delete email for given user

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

```
Robert Schilling's avatar
Robert Schilling committed
678
DELETE /users/:id/emails/:email_id
679 680 681 682
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
683 684
- `id` (required) - id of specified user
- `email_id` (required)  - email ID
685

Douwe Maan's avatar
Douwe Maan committed
686
Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
687

688 689 690 691 692
## Block user

Blocks the specified user.  Available only for admin.

```
693
POST /users/:id/block
694 695 696 697
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
698
- `id` (required) - id of specified user
699

700
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
701
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
702 703 704 705 706 707

## Unblock user

Unblocks the specified user.  Available only for admin.

```
708
POST /users/:id/unblock
709 710 711 712
```

Parameters:

Robert Schilling's avatar
Robert Schilling committed
713
- `id` (required) - id of specified user
714

715
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
716
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
717 718 719

### Get user contribution events

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

James Lopez's avatar
James Lopez committed
722

723
## Get all impersonation tokens of a user
724

725 726 727 728
> 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.
729 730

```
731
GET /users/:user_id/impersonation_tokens
James Lopez's avatar
James Lopez committed
732 733 734 735 736 737
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
738
| `user_id` | integer | yes | The ID of the user |
739 740 741 742 743
| `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
```
744

745
Example response:
746

747 748
```json
[
749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774
   {
      "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"
   }
775 776 777
]
```

778
## Get an impersonation token of a user
779

780 781 782
> Requires admin permissions.

It shows a user's impersonation token.
783 784

```
785
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
786 787 788 789 790 791
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
792 793
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
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
```
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.
820

821
It creates a new impersonation token. Note that only administrators can do this.
822
You are only able to create impersonation tokens to impersonate the user and perform
823
both API calls and Git reads and writes. The user will not see these tokens in their profile
824
settings page.
825 826

```
827
POST /users/:user_id/impersonation_tokens
828 829 830 831
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
832
| `user_id` | integer | yes | The ID of the user |
833 834 835 836 837 838 839
| `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
```
840

841
Example response:
842

843 844
```json
{
845 846 847 848 849 850 851 852 853 854 855
   "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"
856 857
}
```
858

859 860
## Revoke an impersonation token

861 862 863
> Requires admin permissions.

It revokes an impersonation token.
864 865

```
866
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
867 868
```

869 870 871 872
```
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
```

873 874 875 876
Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
877 878
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
Rémy Coutable's avatar
Rémy Coutable committed
879 880 881

### Get user activities (admin only)

882
>**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
Rémy Coutable's avatar
Rémy Coutable committed
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904

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
905
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities
Rémy Coutable's avatar
Rémy Coutable committed
906 907 908 909 910 911 912 913
```

Example response:

```json
[
  {
    "username": "user1",
914 915
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
Rémy Coutable's avatar
Rémy Coutable committed
916 917 918
  },
  {
    "username": "user2",
919 920
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
Rémy Coutable's avatar
Rémy Coutable committed
921 922 923
  },
  {
    "username": "user3",
924 925
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
Rémy Coutable's avatar
Rémy Coutable committed
926 927 928
  }
]
```
929 930

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