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

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 23 24 25 26 27 28 29 30 31 32 33

```
GET /users
```

```json
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
  }
]
```

Ciro Santilli's avatar
Ciro Santilli committed
34
### For admins
35

Nihad Abbasov's avatar
Nihad Abbasov committed
36 37 38 39 40 41 42 43
```
GET /users
```

```json
[
  {
    "id": 1,
44
    "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
45 46
    "email": "john@example.com",
    "name": "John Smith",
47
    "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
48 49 50 51 52
    "created_at": "2012-05-23T08:00:58Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
53
    "website_url": "",
54 55
    "extern_uid": "john.smith",
    "provider": "provider_name",
56
    "theme_id": 1,
57 58
    "color_scheme_id": 2,
    "is_admin": false,
59
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
60
    "can_create_group": true,
Stan Hu's avatar
Stan Hu committed
61 62
    "current_sign_in_at": "2014-03-19T13:12:15Z",
    "two_factor_enabled": true
Nihad Abbasov's avatar
Nihad Abbasov committed
63 64 65
  },
  {
    "id": 2,
66
    "username": "jack_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
67 68
    "email": "jack@example.com",
    "name": "Jack Smith",
69
    "state": "blocked",
Nihad Abbasov's avatar
Nihad Abbasov committed
70 71 72 73 74
    "created_at": "2012-05-23T08:01:01Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
75
    "website_url": "",
76 77
    "extern_uid": "jack.smith",
    "provider": "provider_name",
78
    "theme_id": 1,
79 80
    "color_scheme_id": 3,
    "is_admin": false,
81
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
82
    "can_create_group": true,
83
    "can_create_project": true,
84
    "projects_limit": 100,
Stan Hu's avatar
Stan Hu committed
85 86
    "current_sign_in_at": "2014-03-19T17:54:13Z",
    "two_factor_enabled": false
Nihad Abbasov's avatar
Nihad Abbasov committed
87 88 89 90
  }
]
```

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

93 94 95 96 97 98 99 100 101 102 103
In addition, you can lookup users by username:

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

For example:

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

Nihad Abbasov's avatar
Nihad Abbasov committed
105 106 107 108
## Single user

Get a single user.

Ciro Santilli's avatar
Ciro Santilli committed
109
### For user
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125

```
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",
126 127 128 129 130 131 132
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "website_url": ""
133 134 135
}
```

Ciro Santilli's avatar
Ciro Santilli committed
136
### For admin
137

Nihad Abbasov's avatar
Nihad Abbasov committed
138 139 140 141 142 143
```
GET /users/:id
```

Parameters:

144
- `id` (required) - The ID of a user
Nihad Abbasov's avatar
Nihad Abbasov committed
145 146 147 148

```json
{
  "id": 1,
149
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
150 151
  "email": "john@example.com",
  "name": "John Smith",
152
  "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
153 154 155 156 157
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
158
  "website_url": "",
159 160
  "extern_uid": "john.smith",
  "provider": "provider_name",
161
  "theme_id": 1,
162 163
  "color_scheme_id": 2,
  "is_admin": false,
164
  "can_create_group": true,
165 166
  "can_create_project": true,
  "projects_limit": 100
Nihad Abbasov's avatar
Nihad Abbasov committed
167 168 169
}
```

170
## User creation
171 172

Creates a new user. Note only administrators can create new users.
173 174 175 176 177 178 179

```
POST /users
```

Parameters:

180 181 182 183 184
- `email` (required)            - Email
- `password` (required)         - Password
- `username` (required)         - Username
- `name` (required)             - Name
- `skype` (optional)            - Skype ID
Ciro Santilli's avatar
Ciro Santilli committed
185
- `linkedin` (optional)         - LinkedIn
186
- `twitter` (optional)          - Twitter account
Ciro Santilli's avatar
Ciro Santilli committed
187
- `website_url` (optional)      - Website URL
188 189 190
- `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
191
- `bio` (optional)              - User's biography
192 193
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
194
- `confirm` (optional)          - Require confirmation - true (default) or false
195

196
## User modification
197 198

Modifies an existing user. Only administrators can change attributes of a user.
199 200 201 202 203 204

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

Parameters:
205

Ciro Santilli's avatar
Ciro Santilli committed
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
- `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
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false

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.
224 225

## User deletion
226

Ciro Santilli's avatar
Ciro Santilli committed
227 228
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
229
still returns a status code `200 OK`.
Ciro Santilli's avatar
Ciro Santilli committed
230 231
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
232 233 234 235 236

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

237 238
Parameters:

239
- `id` (required) - The ID of the user
240

Nihad Abbasov's avatar
Nihad Abbasov committed
241 242
## Current user

243
Gets currently authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
244 245 246 247 248 249 250 251

```
GET /user
```

```json
{
  "id": 1,
252
  "username": "john_smith",
Nihad Abbasov's avatar
Nihad Abbasov committed
253 254
  "email": "john@example.com",
  "name": "John Smith",
Alex Denisov's avatar
Alex Denisov committed
255
  "private_token": "dd34asd13as",
256
  "state": "active",
Nihad Abbasov's avatar
Nihad Abbasov committed
257 258 259 260 261
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert's avatar
Jerome Dalbert committed
262
  "website_url": "",
263 264
  "theme_id": 1,
  "color_scheme_id": 2,
Alex Denisov's avatar
Alex Denisov committed
265
  "is_admin": false,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
266
  "can_create_group": true,
267 268
  "can_create_project": true,
  "projects_limit": 100
Nihad Abbasov's avatar
Nihad Abbasov committed
269 270
}
```
271 272 273 274 275 276 277 278 279 280 281 282 283

## 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
284
    "title": "Public key",
285 286
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
287 288 289
  },
  {
    "id": 3,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
290
    "title": "Another Public key",
291 292
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
293 294 295 296
  }
]
```

297 298
Parameters:

299
- **none**
300

301 302 303 304 305 306 307 308 309 310
## List SSH keys for user

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

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

Parameters:

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

313 314 315 316 317 318 319 320 321 322
## Single SSH key

Get a single key.

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

Parameters:

323
- `id` (required) - The ID of an SSH key
324 325 326 327

```json
{
  "id": 1,
Johannes Schleifenbaum's avatar
Johannes Schleifenbaum committed
328
  "title": "Public key",
329 330
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
331 332
}
```
333

334 335
## Add SSH key

336
Creates a new key owned by the currently authenticated user.
337 338 339 340 341 342 343

```
POST /user/keys
```

Parameters:

344
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
345
- `key` (required)   - new SSH key
346

347 348 349 350 351 352 353 354 355
```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
}
```

356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
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"
    ]
  }
}
```

372 373 374 375 376 377 378 379 380 381
## 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
382
- `id` (required)    - id of specified user
383
- `title` (required) - new SSH Key's title
Ciro Santilli's avatar
Ciro Santilli committed
384
- `key` (required)   - new SSH key
385

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

388
## Delete SSH key for current user
389

Ciro Santilli's avatar
Ciro Santilli committed
390 391
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
392
or not available results in `200 OK`.
393 394 395 396 397 398 399

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

Parameters:

400
- `id` (required) - SSH key ID
401

402
## Delete SSH key for given user
403 404 405 406 407 408 409 410 411

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

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

Parameters:

412
- `uid` (required) - id of specified user
Ciro Santilli's avatar
Ciro Santilli committed
413
- `id` (required)  - SSH key ID
414

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

417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
## 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's avatar
Douwe Maan committed
454
## Single email
455

Douwe Maan's avatar
Douwe Maan committed
456
Get a single email.
457 458 459 460 461 462 463

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

Parameters:

Douwe Maan's avatar
Douwe Maan committed
464
- `id` (required) - email ID
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

```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
492
Will return created email with status `201 Created` on success. If an
493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
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's avatar
Douwe Maan committed
518
Will return created email with status `201 Created` on success, or `404 Not found` on fail.
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546

## 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's avatar
Douwe Maan committed
547
Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
548

549 550 551 552 553 554 555 556 557 558 559 560
## Block user

Blocks the specified user.  Available only for admin.

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

Parameters:

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

561 562
Will return `200 OK` on success, `404 User Not Found` is user cannot be found or 
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
563 564 565 566 567 568 569 570 571 572 573 574 575

## Unblock user

Unblocks the specified user.  Available only for admin.

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

Parameters:

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

576 577
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.