# 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" }, { "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" } ] ``` 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 } ``` ## 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.