gitlab-org--gitlab-foss/doc/api/users.md

363 lines
7.6 KiB
Markdown
Raw Normal View History

2014-05-27 08:12:15 -04:00
# Users
2012-07-05 09:57:45 -04:00
## List users
Get a list of users.
2014-04-24 18:48:22 -04:00
2013-04-16 02:26:01 -04:00
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
2012-07-05 09:57:45 -04:00
### 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
2012-07-05 09:57:45 -04:00
```
GET /users
```
```json
[
{
"id": 1,
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
"state": "active",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
"extern_uid": "john.smith",
"provider": "provider_name",
2013-08-30 15:04:26 -04:00
"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
2012-07-05 09:57:45 -04:00
},
{
"id": 2,
"username": "jack_smith",
2012-07-05 09:57:45 -04:00
"email": "jack@example.com",
"name": "Jack Smith",
"state": "blocked",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:01:01Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
"extern_uid": "jack.smith",
"provider": "provider_name",
2013-08-30 15:04:26 -04:00
"theme_id": 1,
"color_scheme_id": 3,
"is_admin": false,
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
2013-10-01 07:52:57 -04:00
"can_create_group": true,
"can_create_project": true
2012-07-05 09:57:45 -04:00
}
]
```
2014-06-25 03:06:39 -04:00
You can search for users by email or username with: `/users?search=John`
2014-04-01 04:41:57 -04:00
Also see `def search query` in `app/models/user.rb`.
2012-07-05 09:57:45 -04:00
## 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
2012-07-05 09:57:45 -04:00
```
GET /users/:id
```
Parameters:
2014-04-24 18:48:22 -04:00
- `id` (required) - The ID of a user
2012-07-05 09:57:45 -04:00
```json
{
"id": 1,
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
"state": "active",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
"extern_uid": "john.smith",
"provider": "provider_name",
2013-08-30 15:04:26 -04:00
"theme_id": 1,
"color_scheme_id": 2,
"is_admin": false,
2013-10-01 07:52:57 -04:00
"can_create_group": true,
"can_create_project": true
2012-07-05 09:57:45 -04:00
}
```
## User creation
Creates a new user. Note only administrators can create new users.
```
POST /users
```
Parameters:
2014-04-24 18:48:22 -04:00
- `email` (required) - Email
- `password` (required) - Password
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
- `linkedin` (optional) - LinkedIn
2014-04-24 18:48:22 -04:00
- `twitter` (optional) - Twitter account
- `website_url` (optional) - Website URL
2014-04-24 18:48:22 -04:00
- `projects_limit` (optional) - Number of projects user can create
- `extern_uid` (optional) - External UID
- `provider` (optional) - External provider name
- `bio` (optional) - User's biography
2014-04-24 18:48:22 -04:00
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true 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:
2014-04-24 18:48:22 -04:00
- `id` (required) - The ID of the user
2012-07-05 09:57:45 -04:00
## Current user
Gets currently authenticated user.
2012-07-05 09:57:45 -04:00
```
GET /user
```
```json
{
"id": 1,
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
2013-03-18 17:06:24 -04:00
"private_token": "dd34asd13as",
"state": "active",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
2013-08-30 15:04:26 -04:00
"theme_id": 1,
"color_scheme_id": 2,
2013-03-18 17:06:24 -04:00
"is_admin": false,
2014-04-05 02:36:47 -04:00
"can_create_group": true,
"can_create_project": true
2012-07-05 09:57:45 -04:00
}
```
2012-09-21 07:49:28 -04:00
## List SSH keys
Get a list of currently authenticated user's SSH keys.
```
GET /user/keys
```
```json
[
{
"id": 1,
2014-04-05 02:36:47 -04:00
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
2012-09-21 07:49:28 -04:00
},
{
"id": 3,
2014-04-05 02:36:47 -04:00
"title": "Another Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
2012-09-21 07:49:28 -04:00
}
]
```
Parameters:
2014-04-24 18:48:22 -04:00
- **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:
2014-04-24 18:48:22 -04:00
- `uid` (required) - id of specified user
2012-09-21 07:49:28 -04:00
## Single SSH key
Get a single key.
```
GET /user/keys/:id
```
Parameters:
2014-04-24 18:48:22 -04:00
- `id` (required) - The ID of an SSH key
2012-09-21 07:49:28 -04:00
```json
{
"id": 1,
2014-04-05 02:36:47 -04:00
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
2012-09-21 07:49:28 -04:00
}
```
2012-09-21 07:49:28 -04:00
## Add SSH key
Creates a new key owned by the currently authenticated user.
2012-09-21 07:49:28 -04:00
```
POST /user/keys
```
Parameters:
2014-04-24 18:48:22 -04:00
- `title` (required) - new SSH Key's title
- `key` (required) - new SSH key
2012-09-21 07:49:28 -04:00
## 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
2014-04-24 18:48:22 -04:00
- `title` (required) - new SSH Key's title
- `key` (required) - new SSH key
2014-04-24 18:48:22 -04:00
Will return created key with status `201 Created` on success, or `404 Not found` on fail.
2014-04-24 18:48:22 -04:00
## Delete SSH key for current user
2012-09-21 07:49:28 -04:00
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`.
2012-09-21 07:49:28 -04:00
```
DELETE /user/keys/:id
```
Parameters:
2014-04-24 18:48:22 -04:00
- `id` (required) - SSH key ID
2012-09-21 07:49:28 -04:00
2014-04-24 18:48:22 -04:00
## Delete SSH key for given user
Deletes key owned by a specified user. Available only for admin.
```
DELETE /users/:uid/keys/:id
```
Parameters:
2014-04-24 18:48:22 -04:00
- `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.