/doc/api/users.md
Markdown | 622 lines | 480 code | 142 blank | 0 comment | 0 complexity | cce09692a0e527c4bacfad5c9d038534 MD5 | raw file
1# Users
2
3## List users
4
5Get a list of users.
6
7This function takes pagination parameters `page` and `per_page` to restrict the list of users.
8
9### For normal users
10
11```
12GET /users
13```
14
15```json
16[
17 {
18 "id": 1,
19 "username": "john_smith",
20 "name": "John Smith",
21 "state": "active",
22 "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
23 "web_url": "http://localhost:3000/u/john_smith"
24 },
25 {
26 "id": 2,
27 "username": "jack_smith",
28 "name": "Jack Smith",
29 "state": "blocked",
30 "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
31 "web_url": "http://localhost:3000/u/jack_smith"
32 }
33]
34```
35
36### For admins
37
38```
39GET /users
40```
41
42```json
43[
44 {
45 "id": 1,
46 "username": "john_smith",
47 "email": "john@example.com",
48 "name": "John Smith",
49 "state": "active",
50 "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
51 "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 "skype": "",
57 "linkedin": "",
58 "twitter": "",
59 "website_url": "",
60 "last_sign_in_at": "2012-06-01T11:41:01Z",
61 "confirmed_at": "2012-05-23T09:05:22Z",
62 "theme_id": 1,
63 "color_scheme_id": 2,
64 "projects_limit": 100,
65 "current_sign_in_at": "2012-06-02T06:36:55Z",
66 "identities": [
67 {"provider": "github", "extern_uid": "2435223452345"},
68 {"provider": "bitbucket", "extern_uid": "john.smith"},
69 {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
70 ],
71 "can_create_group": true,
72 "can_create_project": true,
73 "two_factor_enabled": true,
74 "external": false
75 },
76 {
77 "id": 2,
78 "username": "jack_smith",
79 "email": "jack@example.com",
80 "name": "Jack Smith",
81 "state": "blocked",
82 "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
83 "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 "skype": "",
89 "linkedin": "",
90 "twitter": "",
91 "website_url": "",
92 "last_sign_in_at": null,
93 "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 "identities": [],
99 "can_create_group": true,
100 "can_create_project": true,
101 "two_factor_enabled": true,
102 "external": false
103 }
104]
105```
106
107You can search for users by email or username with: `/users?search=John`
108
109In addition, you can lookup users by username:
110
111```
112GET /users?username=:username
113```
114
115For example:
116
117```
118GET /users?username=jack_smith
119```
120
121## Single user
122
123Get a single user.
124
125### For user
126
127```
128GET /users/:id
129```
130
131Parameters:
132
133- `id` (required) - The ID of a user
134
135```json
136{
137 "id": 1,
138 "username": "john_smith",
139 "name": "John Smith",
140 "state": "active",
141 "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
142 "web_url": "http://localhost:3000/u/john_smith",
143 "created_at": "2012-05-23T08:00:58Z",
144 "is_admin": false,
145 "bio": null,
146 "location": null,
147 "skype": "",
148 "linkedin": "",
149 "twitter": "",
150 "website_url": ""
151}
152```
153
154### For admin
155
156```
157GET /users/:id
158```
159
160Parameters:
161
162- `id` (required) - The ID of a user
163
164```json
165{
166 "id": 1,
167 "username": "john_smith",
168 "email": "john@example.com",
169 "name": "John Smith",
170 "state": "active",
171 "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
172 "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 "skype": "",
178 "linkedin": "",
179 "twitter": "",
180 "website_url": "",
181 "last_sign_in_at": "2012-06-01T11:41:01Z",
182 "confirmed_at": "2012-05-23T09:05:22Z",
183 "theme_id": 1,
184 "color_scheme_id": 2,
185 "projects_limit": 100,
186 "current_sign_in_at": "2012-06-02T06:36:55Z",
187 "identities": [
188 {"provider": "github", "extern_uid": "2435223452345"},
189 {"provider": "bitbucket", "extern_uid": "john.smith"},
190 {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
191 ],
192 "can_create_group": true,
193 "can_create_project": true,
194 "two_factor_enabled": true,
195 "external": false
196}
197```
198
199## User creation
200
201Creates a new user. Note only administrators can create new users.
202
203```
204POST /users
205```
206
207Parameters:
208
209- `email` (required) - Email
210- `password` (required) - Password
211- `username` (required) - Username
212- `name` (required) - Name
213- `skype` (optional) - Skype ID
214- `linkedin` (optional) - LinkedIn
215- `twitter` (optional) - Twitter account
216- `website_url` (optional) - Website URL
217- `projects_limit` (optional) - Number of projects user can create
218- `extern_uid` (optional) - External UID
219- `provider` (optional) - External provider name
220- `bio` (optional) - User's biography
221- `location` (optional) - User's location
222- `admin` (optional) - User is admin - true or false (default)
223- `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
229Modifies an existing user. Only administrators can change attributes of a user.
230
231```
232PUT /users/:id
233```
234
235Parameters:
236
237- `email` - Email
238- `username` - Username
239- `name` - Name
240- `password` - Password
241- `skype` - Skype ID
242- `linkedin` - LinkedIn
243- `twitter` - Twitter account
244- `website_url` - Website URL
245- `projects_limit` - Limit projects each user can create
246- `extern_uid` - External UID
247- `provider` - External provider name
248- `bio` - User's biography
249- `location` (optional) - User's location
250- `admin` (optional) - User is admin - true or false (default)
251- `can_create_group` (optional) - User can create groups - true or false
252- `external` (optional) - Flags the user as external - true or false(default)
253
254Note, at the moment this method does only return a 404 error,
255even in cases where a 409 (Conflict) would be more appropriate,
256e.g. when renaming the email address to some existing one.
257
258## User deletion
259
260Deletes a user. Available only for administrators.
261This is an idempotent function, calling this function for a non-existent user id
262still returns a status code `200 OK`.
263The JSON response differs if the user was actually deleted or not.
264In the former the user is returned and in the latter not.
265
266```
267DELETE /users/:id
268```
269
270Parameters:
271
272- `id` (required) - The ID of the user
273
274## Current user
275
276Gets currently authenticated user.
277
278```
279GET /user
280```
281
282```json
283{
284 "id": 1,
285 "username": "john_smith",
286 "email": "john@example.com",
287 "name": "John Smith",
288 "state": "active",
289 "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
290 "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 "skype": "",
296 "linkedin": "",
297 "twitter": "",
298 "website_url": "",
299 "last_sign_in_at": "2012-06-01T11:41:01Z",
300 "confirmed_at": "2012-05-23T09:05:22Z",
301 "theme_id": 1,
302 "color_scheme_id": 2,
303 "projects_limit": 100,
304 "current_sign_in_at": "2012-06-02T06:36:55Z",
305 "identities": [
306 {"provider": "github", "extern_uid": "2435223452345"},
307 {"provider": "bitbucket", "extern_uid": "john_smith"},
308 {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
309 ],
310 "can_create_group": true,
311 "can_create_project": true,
312 "two_factor_enabled": true,
313 "external": false
314}
315```
316
317## List SSH keys
318
319Get a list of currently authenticated user's SSH keys.
320
321```
322GET /user/keys
323```
324
325```json
326[
327 {
328 "id": 1,
329 "title": "Public key",
330 "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
331 "created_at": "2014-08-01T14:47:39.080Z"
332 },
333 {
334 "id": 3,
335 "title": "Another Public key",
336 "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
337 "created_at": "2014-08-01T14:47:39.080Z"
338 }
339]
340```
341
342Parameters:
343
344- **none**
345
346## List SSH keys for user
347
348Get a list of a specified user's SSH keys. Available only for admin
349
350```
351GET /users/:uid/keys
352```
353
354Parameters:
355
356- `uid` (required) - id of specified user
357
358## Single SSH key
359
360Get a single key.
361
362```
363GET /user/keys/:id
364```
365
366Parameters:
367
368- `id` (required) - The ID of an SSH key
369
370```json
371{
372 "id": 1,
373 "title": "Public key",
374 "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
375 "created_at": "2014-08-01T14:47:39.080Z"
376}
377```
378
379## Add SSH key
380
381Creates a new key owned by the currently authenticated user.
382
383```
384POST /user/keys
385```
386
387Parameters:
388
389- `title` (required) - new SSH Key's title
390- `key` (required) - new SSH key
391
392```json
393{
394 "created_at": "2015-01-21T17:44:33.512Z",
395 "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",
396 "title": "ABC",
397 "id": 4
398}
399```
400
401Will return created key with status `201 Created` on success. If an
402error occurs a `400 Bad Request` is returned with a message explaining the error:
403
404```json
405{
406 "message": {
407 "fingerprint": [
408 "has already been taken"
409 ],
410 "key": [
411 "has already been taken"
412 ]
413 }
414}
415```
416
417## Add SSH key for user
418
419Create new key owned by specified user. Available only for admin
420
421```
422POST /users/:id/keys
423```
424
425Parameters:
426
427- `id` (required) - id of specified user
428- `title` (required) - new SSH Key's title
429- `key` (required) - new SSH key
430
431Will return created key with status `201 Created` on success, or `404 Not found` on fail.
432
433## Delete SSH key for current user
434
435Deletes key owned by currently authenticated user.
436This is an idempotent function and calling it on a key that is already deleted
437or not available results in `200 OK`.
438
439```
440DELETE /user/keys/:id
441```
442
443Parameters:
444
445- `id` (required) - SSH key ID
446
447## Delete SSH key for given user
448
449Deletes key owned by a specified user. Available only for admin.
450
451```
452DELETE /users/:uid/keys/:id
453```
454
455Parameters:
456
457- `uid` (required) - id of specified user
458- `id` (required) - SSH key ID
459
460Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
461
462## List emails
463
464Get a list of currently authenticated user's emails.
465
466```
467GET /user/emails
468```
469
470```json
471[
472 {
473 "id": 1,
474 "email": "email@example.com"
475 },
476 {
477 "id": 3,
478 "email": "email2@example.com"
479 }
480]
481```
482
483Parameters:
484
485- **none**
486
487## List emails for user
488
489Get a list of a specified user's emails. Available only for admin
490
491```
492GET /users/:uid/emails
493```
494
495Parameters:
496
497- `uid` (required) - id of specified user
498
499## Single email
500
501Get a single email.
502
503```
504GET /user/emails/:id
505```
506
507Parameters:
508
509- `id` (required) - email ID
510
511```json
512{
513 "id": 1,
514 "email": "email@example.com"
515}
516```
517
518## Add email
519
520Creates a new email owned by the currently authenticated user.
521
522```
523POST /user/emails
524```
525
526Parameters:
527
528- `email` (required) - email address
529
530```json
531{
532 "id": 4,
533 "email": "email@example.com"
534}
535```
536
537Will return created email with status `201 Created` on success. If an
538error occurs a `400 Bad Request` is returned with a message explaining the error:
539
540```json
541{
542 "message": {
543 "email": [
544 "has already been taken"
545 ]
546 }
547}
548```
549
550## Add email for user
551
552Create new email owned by specified user. Available only for admin
553
554```
555POST /users/:id/emails
556```
557
558Parameters:
559
560- `id` (required) - id of specified user
561- `email` (required) - email address
562
563Will return created email with status `201 Created` on success, or `404 Not found` on fail.
564
565## Delete email for current user
566
567Deletes email owned by currently authenticated user.
568This is an idempotent function and calling it on a email that is already deleted
569or not available results in `200 OK`.
570
571```
572DELETE /user/emails/:id
573```
574
575Parameters:
576
577- `id` (required) - email ID
578
579## Delete email for given user
580
581Deletes email owned by a specified user. Available only for admin.
582
583```
584DELETE /users/:uid/emails/:id
585```
586
587Parameters:
588
589- `uid` (required) - id of specified user
590- `id` (required) - email ID
591
592Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
593
594## Block user
595
596Blocks the specified user. Available only for admin.
597
598```
599PUT /users/:uid/block
600```
601
602Parameters:
603
604- `uid` (required) - id of specified user
605
606Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
607`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
608
609## Unblock user
610
611Unblocks the specified user. Available only for admin.
612
613```
614PUT /users/:uid/unblock
615```
616
617Parameters:
618
619- `uid` (required) - id of specified user
620
621Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
622`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.