BigW Consortium Gitlab

users.md 13.8 KB
Newer Older
1 2
# Users

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/u/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/u/jack_smith"
32 33 34 35
  }
]
```

Ciro Santilli committed
36
### For admins
37

38 39 40 41 42 43 44 45
```
GET /users
```

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

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

109 110 111 112 113 114 115 116 117 118 119
In addition, you can lookup users by username:

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

For example:

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

121 122 123 124
## Single user

Get a single user.

Ciro Santilli committed
125
### For user
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141

```
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",
142
  "web_url": "http://localhost:3000/u/john_smith",
143 144 145
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": null,
146
  "location": null,
147 148 149 150
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "website_url": ""
151 152 153
}
```

Ciro Santilli committed
154
### For admin
155

156 157 158 159 160 161
```
GET /users/:id
```

Parameters:

162
- `id` (required) - The ID of a user
163 164 165 166

```json
{
  "id": 1,
167
  "username": "john_smith",
168 169
  "email": "john@example.com",
  "name": "John Smith",
170
  "state": "active",
171 172
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/u/john_smith",
173
  "created_at": "2012-05-23T08:00:58Z",
174
  "is_admin": false,
175
  "bio": null,
176
  "location": null,
177 178 179
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
180
  "website_url": "",
181 182
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
183
  "theme_id": 1,
184
  "color_scheme_id": 2,
185 186 187 188 189 190 191
  "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"}
  ],
192
  "can_create_group": true,
193
  "can_create_project": true,
194 195
  "two_factor_enabled": true,
  "external": false
196 197 198
}
```

199
## User creation
200 201

Creates a new user. Note only administrators can create new users.
202 203 204 205 206 207 208

```
POST /users
```

Parameters:

209 210 211 212 213
- `email` (required)            - Email
- `password` (required)         - Password
- `username` (required)         - Username
- `name` (required)             - Name
- `skype` (optional)            - Skype ID
Ciro Santilli committed
214
- `linkedin` (optional)         - LinkedIn
215
- `twitter` (optional)          - Twitter account
Ciro Santilli committed
216
- `website_url` (optional)      - Website URL
217 218 219
- `projects_limit` (optional)   - Number of projects user can create
- `extern_uid` (optional)       - External UID
- `provider` (optional)         - External provider name
Ciro Santilli committed
220
- `bio` (optional)              - User's biography
221
- `location` (optional)         - User's location
222 223
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
224
- `confirm` (optional)          - Require confirmation - true (default) or false
225
- `external` (optional)         - Flags the user as external - true or false(default)
226

227
## User modification
228 229

Modifies an existing user. Only administrators can change attributes of a user.
230 231 232 233 234 235

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

Parameters:
236

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

Note, at the moment this method does only return a 404 error,
even in cases where a 409 (Conflict) would be more appropriate,
e.g. when renaming the email address to some existing one.
257 258

## User deletion
259

Ciro Santilli committed
260 261
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
262
still returns a status code `200 OK`.
Ciro Santilli committed
263 264
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
265 266 267 268 269

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

270 271
Parameters:

272
- `id` (required) - The ID of the user
273

274 275
## Current user

276
Gets currently authenticated user.
277 278 279 280 281 282 283 284

```
GET /user
```

```json
{
  "id": 1,
285
  "username": "john_smith",
286 287
  "email": "john@example.com",
  "name": "John Smith",
288
  "state": "active",
289 290
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/u/john_smith",
291
  "created_at": "2012-05-23T08:00:58Z",
292
  "is_admin": false,
293
  "bio": null,
294
  "location": null,
295 296 297
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
298
  "website_url": "",
299 300
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
301 302
  "theme_id": 1,
  "color_scheme_id": 2,
303 304 305 306 307 308 309
  "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"}
  ],
310
  "can_create_group": true,
311
  "can_create_project": true,
312 313 314
  "two_factor_enabled": true,
  "external": false,
  "private_token": "dd34asd13as"
315 316
}
```
317 318 319 320 321 322 323 324 325 326 327 328 329

## List SSH keys

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

```
GET /user/keys
```

```json
[
  {
    "id": 1,
330
    "title": "Public key",
331 332
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
333 334 335
  },
  {
    "id": 3,
336
    "title": "Another Public key",
337 338
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
339 340 341 342
  }
]
```

343 344
Parameters:

345
- **none**
346

347 348 349 350 351 352 353 354 355 356
## List SSH keys for user

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

```
GET /users/:uid/keys
```

Parameters:

357
- `uid` (required) - id of specified user
358

359 360 361 362 363 364 365 366 367 368
## Single SSH key

Get a single key.

```
GET /user/keys/:id
```

Parameters:

369
- `id` (required) - The ID of an SSH key
370 371 372 373

```json
{
  "id": 1,
374
  "title": "Public key",
375 376
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
377 378
}
```
379

380 381
## Add SSH key

382
Creates a new key owned by the currently authenticated user.
383 384 385 386 387 388 389

```
POST /user/keys
```

Parameters:

390
- `title` (required) - new SSH Key's title
Ciro Santilli committed
391
- `key` (required)   - new SSH key
392

393 394 395 396 397 398 399 400 401
```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
}
```

402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417
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"
    ]
  }
}
```

418 419 420 421 422 423 424 425 426 427
## Add SSH key for user

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

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

Parameters:

Ciro Santilli committed
428
- `id` (required)    - id of specified user
429
- `title` (required) - new SSH Key's title
Ciro Santilli committed
430
- `key` (required)   - new SSH key
431

432
Will return created key with status `201 Created` on success, or `404 Not found` on fail.
433

434
## Delete SSH key for current user
435

Ciro Santilli committed
436 437
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
438
or not available results in `200 OK`.
439 440 441 442 443 444 445

```
DELETE /user/keys/:id
```

Parameters:

446
- `id` (required) - SSH key ID
447

448
## Delete SSH key for given user
449 450 451 452 453 454 455 456 457

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

```
DELETE /users/:uid/keys/:id
```

Parameters:

458
- `uid` (required) - id of specified user
Ciro Santilli committed
459
- `id` (required)  - SSH key ID
460

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

463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
## 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

```
GET /users/:uid/emails
```

Parameters:

- `uid` (required) - id of specified user

Douwe Maan committed
500
## Single email
501

Douwe Maan committed
502
Get a single email.
503 504 505 506 507 508 509

```
GET /user/emails/:id
```

Parameters:

Douwe Maan committed
510
- `id` (required) - email ID
511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537

```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
538
Will return created email with status `201 Created` on success. If an
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
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

Douwe Maan committed
564
Will return created email with status `201 Created` on success, or `404 Not found` on fail.
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592

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

```
DELETE /user/emails/:id
```

Parameters:

- `id` (required) - email ID

## Delete email for given user

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

```
DELETE /users/:uid/emails/:id
```

Parameters:

- `uid` (required) - id of specified user
- `id` (required)  - email ID

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

595 596 597 598 599 600 601 602 603 604 605 606
## Block user

Blocks the specified user.  Available only for admin.

```
PUT /users/:uid/block
```

Parameters:

- `uid` (required) - id of specified user

607
Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
608
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
609 610 611 612 613 614 615 616 617 618 619 620 621

## Unblock user

Unblocks the specified user.  Available only for admin.

```
PUT /users/:uid/unblock
```

Parameters:

- `uid` (required) - id of specified user

622 623
Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.