2017-05-10 14:48:07 -04:00
# Users API
2014-05-27 08:12:15 -04:00
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
2014-06-25 03:18:52 -04:00
### For normal users
2014-06-13 11:02:42 -04:00
```
GET /users
```
```json
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/john_smith"
2014-06-13 11:02:42 -04:00
},
{
"id": 2,
"username": "jack_smith",
"name": "Jack Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/jack_smith"
2014-06-13 11:02:42 -04:00
}
]
```
2016-10-25 17:08:53 -04:00
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
```
2014-06-25 03:18:52 -04:00
### For admins
2014-06-13 11:02:42 -04:00
2012-07-05 09:57:45 -04:00
```
GET /users
```
```json
[
{
"id": 1,
2012-12-10 17:46:31 -05:00
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 19:41:15 -04:00
"state": "active",
2016-05-01 16:48:26 -04:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-05-01 16:48:26 -04:00
"location": null,
2012-07-05 09:57:45 -04:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
2016-09-26 13:33:00 -04:00
"organization": "",
2016-05-01 16:48:26 -04:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2012-05-23",
2013-07-31 06:52:23 -04:00
"color_scheme_id": 2,
2016-05-01 16:48:26 -04:00
"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"}
],
2015-02-09 07:52:42 -05:00
"can_create_group": true,
2016-05-01 16:48:26 -04:00
"can_create_project": true,
"two_factor_enabled": true,
"external": false
2012-07-05 09:57:45 -04:00
},
{
"id": 2,
2012-12-10 17:46:31 -05:00
"username": "jack_smith",
2012-07-05 09:57:45 -04:00
"email": "jack@example.com",
"name": "Jack Smith",
2013-05-28 19:41:15 -04:00
"state": "blocked",
2016-05-01 16:48:26 -04:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/jack_smith",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:01:01Z",
"bio": null,
2016-04-05 19:57:21 -04:00
"location": null,
2012-07-05 09:57:45 -04:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
2016-09-26 13:33:00 -04:00
"organization": "",
2016-05-01 16:48:26 -04:00
"last_sign_in_at": null,
"confirmed_at": "2012-05-30T16:53:06.148Z",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2012-05-23",
2013-07-31 06:52:23 -04:00
"color_scheme_id": 3,
2015-02-09 07:52:42 -05:00
"projects_limit": 100,
2015-06-24 01:36:35 -04:00
"current_sign_in_at": "2014-03-19T17:54:13Z",
2016-05-01 16:48:26 -04:00
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": true,
"external": false
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
2015-12-13 01:02:05 -05:00
In addition, you can lookup users by username:
```
GET /users?username=:username
```
For example:
```
GET /users?username=jack_smith
```
2013-02-18 05:15:26 -05:00
2017-02-15 20:44:36 -05:00
You can also lookup users by external UID and provider:
```
GET /users?extern_uid=:extern_uid& provider=:provider
```
For example:
```
GET /users?extern_uid=1234567& provider=github
```
2016-10-25 17:08:53 -04:00
You can search for users who are external with: `/users?external=true`
2012-07-05 09:57:45 -04:00
## Single user
Get a single user.
2014-06-25 03:18:52 -04:00
### For user
2014-06-13 11:02:42 -04:00
```
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",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/john_smith",
2015-12-28 09:50:44 -05:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-04-05 19:57:21 -04:00
"location": null,
2015-12-28 09:50:44 -05:00
"skype": "",
"linkedin": "",
"twitter": "",
2016-09-26 13:33:00 -04:00
"website_url": "",
"organization": ""
2014-06-13 11:02:42 -04:00
}
```
2014-06-25 03:18:52 -04:00
### For admin
2014-06-13 11:02:42 -04:00
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,
2012-12-10 17:46:31 -05:00
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 19:41:15 -04:00
"state": "active",
2016-05-01 16:48:26 -04:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-04-05 19:57:21 -04:00
"location": null,
2012-07-05 09:57:45 -04:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
2016-09-26 13:33:00 -04:00
"organization": "",
2016-05-01 16:48:26 -04:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2012-05-23",
2013-07-31 06:52:23 -04:00
"color_scheme_id": 2,
2016-05-01 16:48:26 -04:00
"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"}
],
2013-10-01 07:52:57 -04:00
"can_create_group": true,
2014-11-01 19:14:42 -04:00
"can_create_project": true,
2016-05-01 16:48:26 -04:00
"two_factor_enabled": true,
"external": false
2012-07-05 09:57:45 -04:00
}
```
2012-10-02 05:52:13 -04:00
## User creation
2013-02-20 06:10:51 -05:00
2017-02-03 09:49:27 -05:00
Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority).
2012-10-02 05:52:13 -04:00
```
POST /users
```
Parameters:
2014-04-24 18:48:22 -04:00
- `email` (required) - Email
2017-02-03 09:49:27 -05:00
- `password` (optional) - Password
- `reset_password` (optional) - Send user password reset link - true or false(default)
2014-04-24 18:48:22 -04:00
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
2014-06-25 03:18:52 -04:00
- `linkedin` (optional) - LinkedIn
2014-04-24 18:48:22 -04:00
- `twitter` (optional) - Twitter account
2014-06-25 03:18:52 -04:00
- `website_url` (optional) - Website URL
2016-09-26 13:33:00 -04:00
- `organization` (optional) - Organization name
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
2014-06-25 03:18:52 -04:00
- `bio` (optional) - User's biography
2016-04-05 19:57:21 -04:00
- `location` (optional) - User's location
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
2014-06-18 13:49:39 -04:00
- `confirm` (optional) - Require confirmation - true (default) or false
2016-03-14 19:11:20 -04:00
- `external` (optional) - Flags the user as external - true or false(default)
2012-10-02 05:52:13 -04:00
2012-12-18 14:24:31 -05:00
## User modification
2013-02-20 06:10:51 -05:00
Modifies an existing user. Only administrators can change attributes of a user.
2012-12-18 14:24:31 -05:00
```
PUT /users/:id
```
Parameters:
2013-02-20 06:10:51 -05:00
2014-06-25 03:18:52 -04:00
- `email` - Email
- `username` - Username
- `name` - Name
- `password` - Password
- `skype` - Skype ID
- `linkedin` - LinkedIn
- `twitter` - Twitter account
- `website_url` - Website URL
2016-09-26 13:33:00 -04:00
- `organization` - Organization name
2014-06-25 03:18:52 -04:00
- `projects_limit` - Limit projects each user can create
- `extern_uid` - External UID
- `provider` - External provider name
- `bio` - User's biography
2016-04-05 19:57:21 -04:00
- `location` (optional) - User's location
2014-06-25 03:18:52 -04:00
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
2016-03-17 06:21:12 -04:00
- `external` (optional) - Flags the user as external - true or false(default)
2014-06-25 03:18:52 -04:00
2017-02-02 10:15:02 -05:00
On password update, user will be forced to change it upon next login.
2016-11-24 12:28:52 -05:00
Note, at the moment this method does only return a `404` error,
even in cases where a `409` (Conflict) would be more appropriate,
2014-06-25 03:18:52 -04:00
e.g. when renaming the email address to some existing one.
2012-12-18 14:24:31 -05:00
## User deletion
2013-02-20 06:10:51 -05:00
2014-06-25 03:18:52 -04:00
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
2014-08-15 10:03:01 -04:00
still returns a status code `200 OK` .
2014-06-25 03:18:52 -04:00
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
2012-12-18 14:24:31 -05:00
```
DELETE /users/:id
```
2013-02-20 06:10:51 -05:00
Parameters:
2014-04-24 18:48:22 -04:00
- `id` (required) - The ID of the user
2017-06-01 12:14:39 -04:00
- `hard_delete` (optional) - If true, contributions that would usually be
[moved to the ghost user ](../user/profile/account/delete_account.md#associated-records )
will be deleted instead, as well as groups owned solely by this user.
2012-12-18 14:24:31 -05:00
2016-11-21 07:59:37 -05:00
## User
### For normal users
2012-07-05 09:57:45 -04:00
2013-02-20 06:10:51 -05:00
Gets currently authenticated user.
2012-07-05 09:57:45 -04:00
```
GET /user
```
```json
{
"id": 1,
2012-12-10 17:46:31 -05:00
"username": "john_smith",
2012-07-05 09:57:45 -04:00
"email": "john@example.com",
"name": "John Smith",
2013-05-28 19:41:15 -04:00
"state": "active",
2016-05-01 16:48:26 -04:00
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
2016-10-13 07:24:09 -04:00
"web_url": "http://localhost:3000/john_smith",
2012-07-05 09:57:45 -04:00
"created_at": "2012-05-23T08:00:58Z",
"bio": null,
2016-04-05 19:57:21 -04:00
"location": null,
2012-07-05 09:57:45 -04:00
"skype": "",
"linkedin": "",
"twitter": "",
2014-01-18 14:07:00 -05:00
"website_url": "",
2016-09-26 13:33:00 -04:00
"organization": "",
2016-05-01 16:48:26 -04:00
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2012-05-23",
2013-08-30 15:04:26 -04:00
"color_scheme_id": 2,
2016-05-01 16:48:26 -04:00
"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"}
],
2014-04-05 02:36:47 -04:00
"can_create_group": true,
2014-11-01 19:14:42 -04:00
"can_create_project": true,
2016-05-01 16:48:26 -04:00
"two_factor_enabled": true,
2016-08-26 00:07:57 -04:00
"external": false
2012-07-05 09:57:45 -04:00
}
```
2012-09-21 07:49:28 -04:00
2016-11-21 07:59:37 -05:00
### 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",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2012-05-23",
2016-11-21 07:59:37 -05:00
"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"
}
```
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",
2014-11-18 07:59:04 -05:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 07:49:28 -04:00
},
{
"id": 3,
2014-04-05 02:36:47 -04:00
"title": "Another Public key",
2014-11-18 07:59:04 -05:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 07:49:28 -04:00
}
]
```
2013-02-20 06:10:51 -05:00
Parameters:
2014-04-24 18:48:22 -04:00
- **none**
2013-02-20 06:10:51 -05:00
2014-04-15 10:39:46 -04:00
## List SSH keys for user
Get a list of a specified user's SSH keys. Available only for admin
```
2016-10-27 04:20:06 -04:00
GET /users/:id/keys
2014-04-15 10:39:46 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
2013-02-20 06:10:51 -05:00
2012-09-21 07:49:28 -04:00
## Single SSH key
Get a single key.
```
2016-10-27 04:20:06 -04:00
GET /user/keys/:key_id
2012-09-21 07:49:28 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `key_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",
2014-11-18 07:59:04 -05:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2014-08-01T14:47:39.080Z"
2012-09-21 07:49:28 -04:00
}
```
2013-02-20 06:10:51 -05:00
2012-09-21 07:49:28 -04:00
## Add SSH key
2013-02-20 06:10:51 -05:00
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
2014-06-25 03:18:52 -04:00
- `key` (required) - new SSH key
2012-09-21 07:49:28 -04:00
2015-01-21 12:57:54 -05:00
```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
}
```
2015-01-21 13:08:15 -05:00
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"
]
}
}
```
2013-03-05 23:48:40 -05:00
## Add SSH key for user
Create new key owned by specified user. Available only for admin
```
POST /users/:id/keys
```
Parameters:
2014-06-25 03:18:52 -04:00
- `id` (required) - id of specified user
2014-04-24 18:48:22 -04:00
- `title` (required) - new SSH Key's title
2014-06-25 03:18:52 -04:00
- `key` (required) - new SSH key
2013-03-05 23:48:40 -05:00
2014-04-24 18:48:22 -04:00
## Delete SSH key for current user
2012-09-21 07:49:28 -04:00
2014-06-25 03:18:52 -04:00
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
2014-08-15 10:03:01 -04:00
or not available results in `200 OK` .
2012-09-21 07:49:28 -04:00
```
2016-10-27 04:20:06 -04:00
DELETE /user/keys/:key_id
2012-09-21 07:49:28 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `key_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
2014-04-15 10:39:46 -04:00
Deletes key owned by a specified user. Available only for admin.
```
2016-10-27 04:20:06 -04:00
DELETE /users/:id/keys/:key_id
2014-04-15 10:39:46 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
- `key_id` (required) - SSH key ID
2014-04-15 10:39:46 -04:00
2014-08-15 10:03:01 -04:00
Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
2015-04-28 12:02:44 -04:00
2015-07-29 09:40:08 -04:00
## 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
```
2016-10-27 04:20:06 -04:00
GET /users/:id/emails
2015-07-29 09:40:08 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
2015-07-29 09:40:08 -04:00
2015-07-30 05:41:59 -04:00
## Single email
2015-07-29 09:40:08 -04:00
2015-07-30 05:41:59 -04:00
Get a single email.
2015-07-29 09:40:08 -04:00
```
2016-10-27 04:20:06 -04:00
GET /user/emails/:email_id
2015-07-29 09:40:08 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `email_id` (required) - email ID
2015-07-29 09:40:08 -04:00
```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"
}
```
2015-07-30 05:41:59 -04:00
Will return created email with status `201 Created` on success. If an
2015-07-29 09:40:08 -04:00
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
## 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` .
```
2016-10-27 04:20:06 -04:00
DELETE /user/emails/:email_id
2015-07-29 09:40:08 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `email_id` (required) - email ID
2015-07-29 09:40:08 -04:00
## Delete email for given user
Deletes email owned by a specified user. Available only for admin.
```
2016-10-27 04:20:06 -04:00
DELETE /users/:id/emails/:email_id
2015-07-29 09:40:08 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
- `email_id` (required) - email ID
2015-07-29 09:40:08 -04:00
2015-07-30 05:41:59 -04:00
Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
2015-07-29 09:40:08 -04:00
2015-04-28 12:02:44 -04:00
## Block user
Blocks the specified user. Available only for admin.
```
2017-02-20 07:31:11 -05:00
POST /users/:id/block
2015-04-28 12:02:44 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
2015-04-28 12:02:44 -04:00
2017-02-20 07:31:11 -05:00
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
2015-12-30 13:52:02 -05:00
`403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
2015-04-28 12:02:44 -04:00
## Unblock user
Unblocks the specified user. Available only for admin.
```
2017-02-20 07:31:11 -05:00
POST /users/:id/unblock
2015-04-28 12:02:44 -04:00
```
Parameters:
2016-10-27 04:20:06 -04:00
- `id` (required) - id of specified user
2015-04-28 12:02:44 -04:00
2017-02-20 07:31:11 -05:00
Will return `201 OK` on success, `404 User Not Found` is user cannot be found or
2015-12-30 13:52:02 -05:00
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
2016-10-10 07:35:26 -04:00
### Get user contribution events
2017-05-29 01:49:17 -04:00
Please refer to the [Events API documentation ](events.md#get-user-contribution-events )
2016-10-10 07:35:26 -04:00
2017-01-04 05:51:17 -05:00
2017-03-17 10:23:52 -04:00
## Get all impersonation tokens of a user
2017-01-04 05:51:17 -05:00
2017-03-17 10:23:52 -04:00
> Requires admin permissions.
It retrieves every impersonation token of the user. Use the pagination
parameters `page` and `per_page` to restrict the list of impersonation tokens.
2017-01-04 05:51:17 -05:00
```
2017-03-01 11:59:03 -05:00
GET /users/:user_id/impersonation_tokens
2017-01-04 05:51:17 -05:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-03-01 11:59:03 -05:00
| `user_id` | integer | yes | The ID of the user |
2017-03-17 10:23:52 -04:00
| `state` | string | no | filter tokens based on state (`all`, `active` , `inactive` ) |
```
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
```
2017-01-04 05:51:17 -05:00
2017-02-27 13:56:54 -05:00
Example response:
2017-03-17 10:23:52 -04:00
2017-01-04 05:51:17 -05:00
```json
[
2017-03-17 10:23:52 -04:00
{
"active" : true,
"token" : "EsMo-vhKfXGwX9RKrwiy",
"scopes" : [
"api"
],
"revoked" : false,
"name" : "mytoken",
"id" : 2,
"created_at" : "2017-03-17T17:18:09.283Z",
"impersonation" : true,
"expires_at" : "2017-04-04"
},
{
"active" : false,
"scopes" : [
"read_user"
],
"revoked" : true,
"token" : "ZcZRpLeEuQRprkRjYydY",
"name" : "mytoken2",
"created_at" : "2017-03-17T17:19:28.697Z",
"id" : 3,
"impersonation" : true,
"expires_at" : "2017-04-14"
}
2017-01-04 05:51:17 -05:00
]
```
2017-03-17 10:23:52 -04:00
## Get an impersonation token of a user
2017-02-09 10:21:09 -05:00
2017-03-17 10:23:52 -04:00
> Requires admin permissions.
It shows a user's impersonation token.
2017-02-09 10:21:09 -05:00
```
2017-03-01 11:59:03 -05:00
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
2017-02-09 10:21:09 -05:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-03-01 11:59:03 -05:00
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
2017-02-09 10:21:09 -05:00
2017-03-17 10:23:52 -04:00
```
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
```
Example response:
```json
{
"active" : true,
"token" : "EsMo-vhKfXGwX9RKrwiy",
"scopes" : [
"api"
],
"revoked" : false,
"name" : "mytoken",
"id" : 2,
"created_at" : "2017-03-17T17:18:09.283Z",
"impersonation" : true,
"expires_at" : "2017-04-04"
}
```
## Create an impersonation token
> Requires admin permissions.
2017-01-04 05:51:17 -05:00
2017-03-01 11:59:03 -05:00
It creates a new impersonation token. Note that only administrators can do this.
2017-02-09 10:21:09 -05:00
You are only able to create impersonation tokens to impersonate the user and perform
both API calls and Git reads and writes. The user will not see these tokens in his profile
settings page.
2017-01-04 05:51:17 -05:00
```
2017-03-01 11:59:03 -05:00
POST /users/:user_id/impersonation_tokens
2017-01-04 05:51:17 -05:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-03-01 11:59:03 -05:00
| `user_id` | integer | yes | The ID of the user |
2017-03-17 10:23:52 -04:00
| `name` | string | yes | The name of the impersonation token |
| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user` ) |
```
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
```
2017-01-04 05:51:17 -05:00
2017-03-01 11:59:03 -05:00
Example response:
2017-03-17 10:23:52 -04:00
2017-03-01 11:59:03 -05:00
```json
{
2017-03-17 10:23:52 -04:00
"id" : 2,
"revoked" : false,
"scopes" : [
"api"
],
"token" : "EsMo-vhKfXGwX9RKrwiy",
"active" : true,
"impersonation" : true,
"name" : "mytoken",
"created_at" : "2017-03-17T17:18:09.283Z",
"expires_at" : "2017-04-04"
2017-03-01 11:59:03 -05:00
}
```
2017-01-04 05:51:17 -05:00
2017-03-01 11:59:03 -05:00
## Revoke an impersonation token
2017-03-17 10:23:52 -04:00
> Requires admin permissions.
It revokes an impersonation token.
2017-01-04 05:51:17 -05:00
```
2017-03-01 11:59:03 -05:00
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
2017-01-04 05:51:17 -05:00
```
2017-03-17 10:23:52 -04:00
```
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
```
2017-01-04 05:51:17 -05:00
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-03-01 11:59:03 -05:00
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
2017-04-12 07:19:45 -04:00
### Get user activities (admin only)
>**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
Get the last activity date for all users, sorted from oldest to newest.
The activities that update the timestamp are:
- Git HTTP/SSH activities (such as clone, push)
- User logging in into GitLab
By default, it shows the activity for all users in the last 6 months, but this can be
amended by using the `from` parameter.
```
GET /user/activities
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` . Defaults to 6 months ago. |
```bash
2017-04-20 09:47:44 -04:00
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities
2017-04-12 07:19:45 -04:00
```
Example response:
```json
[
{
"username": "user1",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2015-12-14",
"last_activity_at": "2015-12-14"
2017-04-12 07:19:45 -04:00
},
{
"username": "user2",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2015-12-15",
"last_activity_at": "2015-12-15"
2017-04-12 07:19:45 -04:00
},
{
"username": "user3",
2017-03-27 09:43:10 -04:00
"last_activity_on": "2015-12-16",
"last_activity_at": "2015-12-16"
2017-04-12 07:19:45 -04:00
}
]
2017-03-27 09:43:10 -04:00
```
Please note that `last_activity_at` is deprecated, please use `last_activity_on` .