# Users ## List users Get a list of users. This function takes pagination parameters `page` and `per_page` to restrict the list of users. ### For normal users ``` 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", } ] ``` ### For admins ``` GET /users ``` ```json [ { "id": 1, "username": "john_smith", "email": "john@example.com", "name": "John Smith", "state": "active", "created_at": "2012-05-23T08:00:58Z", "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", "extern_uid": "john.smith", "provider": "provider_name", "theme_id": 1, "color_scheme_id": 2, "is_admin": false, "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", "can_create_group": true, "current_sign_in_at": "2014-03-19T13:12:15Z", "two_factor_enabled": true }, { "id": 2, "username": "jack_smith", "email": "jack@example.com", "name": "Jack Smith", "state": "blocked", "created_at": "2012-05-23T08:01:01Z", "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", "extern_uid": "jack.smith", "provider": "provider_name", "theme_id": 1, "color_scheme_id": 3, "is_admin": false, "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", "can_create_group": true, "can_create_project": true, "projects_limit": 100, "current_sign_in_at": "2014-03-19T17:54:13Z", "two_factor_enabled": false } ] ``` You can search for users by email or username with: `/users?search=John` Also see `def search query` in `app/models/user.rb`. ## Single user Get a single user. ### For user ``` 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", } ``` ### For admin ``` GET /users/:id ``` Parameters: - `id` (required) - The ID of a user ```json { "id": 1, "username": "john_smith", "email": "john@example.com", "name": "John Smith", "state": "active", "created_at": "2012-05-23T08:00:58Z", "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", "extern_uid": "john.smith", "provider": "provider_name", "theme_id": 1, "color_scheme_id": 2, "is_admin": false, "can_create_group": true, "can_create_project": true, "projects_limit": 100 } ``` ### Get SSH key with user by ID of an SSH key Get SSH key with user by ID of an SSH key. Note only administrators can lookup SSH key with user by ID of an SSH key. ``` GET /keys/:id ``` Parameters: - `id` (required) - The ID of an SSH key ```json { "id": 1, "title": "Sample key 25", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2015-09-03T07:24:44.627Z", "user": { "name": "John Smith", "username": "john_smith", "id": 25, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/cfa35b8cd2ec278026357769582fa563?s=40\u0026d=identicon", "web_url": "http://localhost:3000/u/john_smith", "created_at": "2015-09-03T07:24:01.670Z", "is_admin": false, "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", "email": "john@example.com", "theme_id": 2, "color_scheme_id": 1, "projects_limit": 10, "current_sign_in_at": null, "identities": [], "can_create_group": true, "can_create_project": true, "two_factor_enabled": false } } ``` ## User creation Creates a new user. Note only administrators can create new users. ``` POST /users ``` Parameters: - `email` (required) - Email - `password` (required) - Password - `username` (required) - Username - `name` (required) - Name - `skype` (optional) - Skype ID - `linkedin` (optional) - LinkedIn - `twitter` (optional) - Twitter account - `website_url` (optional) - Website URL - `projects_limit` (optional) - Number of projects user can create - `extern_uid` (optional) - External UID - `provider` (optional) - External provider name - `bio` (optional) - User's biography - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false - `confirm` (optional) - Require confirmation - true (default) or false ## User modification Modifies an existing user. Only administrators can change attributes of a user. ``` PUT /users/:id ``` Parameters: - `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. ## User deletion Deletes a user. Available only for administrators. This is an idempotent function, calling this function for a non-existent user id still returns a status code `200 OK`. The JSON response differs if the user was actually deleted or not. In the former the user is returned and in the latter not. ``` DELETE /users/:id ``` Parameters: - `id` (required) - The ID of the user ## Current user Gets currently authenticated user. ``` GET /user ``` ```json { "id": 1, "username": "john_smith", "email": "john@example.com", "name": "John Smith", "private_token": "dd34asd13as", "state": "active", "created_at": "2012-05-23T08:00:58Z", "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", "theme_id": 1, "color_scheme_id": 2, "is_admin": false, "can_create_group": true, "can_create_project": true, "projects_limit": 100 } ``` ## List SSH keys Get a list of currently authenticated user's SSH keys. ``` GET /user/keys ``` ```json [ { "id": 1, "title": "Public key", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2014-08-01T14:47:39.080Z" }, { "id": 3, "title": "Another Public key", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2014-08-01T14:47:39.080Z" } ] ``` Parameters: - **none** ## List SSH keys for user Get a list of a specified user's SSH keys. Available only for admin ``` GET /users/:uid/keys ``` Parameters: - `uid` (required) - id of specified user ## Single SSH key Get a single key. ``` GET /user/keys/:id ``` Parameters: - `id` (required) - The ID of an SSH key ```json { "id": 1, "title": "Public key", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2014-08-01T14:47:39.080Z" } ``` ## Add SSH key Creates a new key owned by the currently authenticated user. ``` POST /user/keys ``` Parameters: - `title` (required) - new SSH Key's title - `key` (required) - new SSH key ```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 } ``` 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" ] } } ``` ## Add SSH key for user Create new key owned by specified user. Available only for admin ``` POST /users/:id/keys ``` Parameters: - `id` (required) - id of specified user - `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. 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 ``` Parameters: - `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 ``` Parameters: - `uid` (required) - id of specified user - `id` (required) - SSH key ID Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found. ## 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 ## Single email Get a single email. ``` GET /user/emails/:id ``` Parameters: - `id` (required) - email ID ```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" } ``` Will return created email with status `201 Created` on success. If an 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 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. 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 Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found. ## Block user Blocks the specified user. Available only for admin. ``` PUT /users/:uid/block ``` Parameters: - `uid` (required) - id of specified user Will return `200 OK` on success, or `404 User Not Found` is user cannot be found. ## Unblock user Unblocks the specified user. Available only for admin. ``` PUT /users/:uid/unblock ``` Parameters: - `uid` (required) - id of specified user Will return `200 OK` on success, or `404 User Not Found` is user cannot be found.