PageRenderTime 46ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/api/users.md

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