diff options
Diffstat (limited to 'doc/api/users.md')
| -rw-r--r-- | doc/api/users.md | 117 |
1 files changed, 88 insertions, 29 deletions
diff --git a/doc/api/users.md b/doc/api/users.md index a50ba5432fe..28b6c7bd491 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -33,6 +33,18 @@ GET /users ] ``` +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 +``` + ### For admins ``` @@ -120,6 +132,8 @@ For example: GET /users?username=jack_smith ``` +You can search for users who are external with: `/users?external=true` + ## Single user Get a single user. @@ -257,8 +271,8 @@ Parameters: - `can_create_group` (optional) - User can create groups - true or false - `external` (optional) - Flags the user as external - true or false(default) -Note, at the moment this method does only return a 404 error, -even in cases where a 409 (Conflict) would be more appropriate, +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. ## User deletion @@ -277,7 +291,9 @@ Parameters: - `id` (required) - The ID of the user -## Current user +## User + +### For normal users Gets currently authenticated user. @@ -321,6 +337,53 @@ GET /user } ``` +### For admins + +Parameters: + +- `sudo` (required) - the ID of a user + +``` +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", + "theme_id": 1, + "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" +} +``` + ## List SSH keys Get a list of currently authenticated user's SSH keys. @@ -355,24 +418,24 @@ Parameters: Get a list of a specified user's SSH keys. Available only for admin ``` -GET /users/:uid/keys +GET /users/:id/keys ``` Parameters: -- `uid` (required) - id of specified user +- `id` (required) - id of specified user ## Single SSH key Get a single key. ``` -GET /user/keys/:id +GET /user/keys/:key_id ``` Parameters: -- `id` (required) - The ID of an SSH key +- `key_id` (required) - The ID of an SSH key ```json { @@ -435,8 +498,6 @@ Parameters: - `title` (required) - new SSH Key's title - `key` (required) - new SSH key -Will return created key with status `201 Created` on success, or `404 Not found` on fail. - ## Delete SSH key for current user Deletes key owned by currently authenticated user. @@ -444,25 +505,25 @@ This is an idempotent function and calling it on a key that is already deleted or not available results in `200 OK`. ``` -DELETE /user/keys/:id +DELETE /user/keys/:key_id ``` Parameters: -- `id` (required) - SSH key ID +- `key_id` (required) - SSH key ID ## Delete SSH key for given user Deletes key owned by a specified user. Available only for admin. ``` -DELETE /users/:uid/keys/:id +DELETE /users/:id/keys/:key_id ``` Parameters: -- `uid` (required) - id of specified user -- `id` (required) - SSH key ID +- `id` (required) - id of specified user +- `key_id` (required) - SSH key ID Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found. @@ -496,24 +557,24 @@ Parameters: Get a list of a specified user's emails. Available only for admin ``` -GET /users/:uid/emails +GET /users/:id/emails ``` Parameters: -- `uid` (required) - id of specified user +- `id` (required) - id of specified user ## Single email Get a single email. ``` -GET /user/emails/:id +GET /user/emails/:email_id ``` Parameters: -- `id` (required) - email ID +- `email_id` (required) - email ID ```json { @@ -567,8 +628,6 @@ Parameters: - `id` (required) - id of specified user - `email` (required) - email address -Will return created email with status `201 Created` on success, or `404 Not found` on fail. - ## Delete email for current user Deletes email owned by currently authenticated user. @@ -576,25 +635,25 @@ 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 +DELETE /user/emails/:email_id ``` Parameters: -- `id` (required) - email ID +- `email_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 +DELETE /users/:id/emails/:email_id ``` Parameters: -- `uid` (required) - id of specified user -- `id` (required) - email ID +- `id` (required) - id of specified user +- `email_id` (required) - email ID Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found. @@ -603,12 +662,12 @@ Will return `200 OK` on success, or `404 Not found` if either user or email cann Blocks the specified user. Available only for admin. ``` -PUT /users/:uid/block +PUT /users/:id/block ``` Parameters: -- `uid` (required) - id of specified user +- `id` (required) - id of specified user 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. @@ -618,12 +677,12 @@ Will return `200 OK` on success, `404 User Not Found` is user cannot be found or Unblocks the specified user. Available only for admin. ``` -PUT /users/:uid/unblock +PUT /users/:id/unblock ``` Parameters: -- `uid` (required) - id of specified user +- `id` (required) - id of specified user 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. |