# Users API

## List users

Active users = Total accounts - Blocked 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",

    "web_url": "http://localhost:3000/john_smith"

  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",

    "web_url": "http://localhost:3000/jack_smith"

  }
]
```

You can also search for users by name or primary email using `?search=`. For example. `/users?search=John`.

In addition, you can lookup users by username:

```
GET /users?username=:username
```

For example:

```
GET /users?username=jack_smith
```

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
```

NOTE: **Note:**
Username search is case insensitive.

### For admins

```
GET /users
```

| Attribute    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `order_by`   | string | no       | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` |
| `sort`       | string | no       | Return users sorted in `asc` or `desc` order. Default is `desc` |
| `two_factor` | string | no       | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |

```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,

    "last_activity_on": "2012-05-23",

    "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_profile": false

  },
  {
    "id": 2,

    "username": "jack_smith",

    "email": "jack@example.com",
    "name": "Jack Smith",

    "state": "blocked",

    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",

    "web_url": "http://localhost:3000/jack_smith",

    "created_at": "2012-05-23T08:01:01Z",

    "is_admin": false,

    "bio": null,

    "location": null,

    "skype": "",
    "linkedin": "",
    "twitter": "",

    "website_url": "",

    "organization": "",

    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",

    "theme_id": 1,

    "last_activity_on": "2012-05-23",

    "color_scheme_id": 3,

    "projects_limit": 100,

    "current_sign_in_at": "2014-03-19T17:54:13Z",

    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,

    "external": false,

    "private_profile": false

  }
]
```

Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.

```json
[
  {
    "id": 1,
    ...
    "shared_runners_minutes_limit": 133,
    "extra_shared_runners_minutes_limit": 133,
    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
    ...
  }
]
```

Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see
the `group_saml` provider option:

```json
[
  {
    "id": 1,
    ...
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
    ],
    ...
  }
]

```

You can lookup users by external UID and provider:

```
GET /users?extern_uid=:extern_uid&provider=:provider
```

For example:

```
GET /users?extern_uid=1234567&provider=github
```

You can search for users who are external with: `/users?external=true`

You can search users by creation date time range with:

```
GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060
```

You can filter by [custom attributes](custom_attributes.md) with:

```
GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

You can include the users' [custom attributes](custom_attributes.md) in the response with:

```
GET /users?with_custom_attributes=true
```

## 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",

  "web_url": "http://localhost:3000/john_smith",

  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,

  "location": null,

  "public_email": "john@example.com",

  "skype": "",
  "linkedin": "",
  "twitter": "",

  "website_url": "",
  "organization": ""

}
```

### For admin

```
GET /users/:id
```

Parameters:

- `id` (required) - The ID of a user

Example Responses:

```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,

  "public_email": "john@example.com",

  "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,

  "last_activity_on": "2012-05-23",

  "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_profile": false

}
```

Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see

the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.

```json
{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,

  "extra_shared_runners_minutes_limit": 133,
  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"

  ...
}
```

Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also
see the `group_saml` option:

```json
{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,

  "extra_shared_runners_minutes_limit": 133,
  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"

  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
  ],

  ...
}
```

You can include the user's [custom attributes](custom_attributes.md) in the response with:

```
GET /users/:id?with_custom_attributes=true
```

## User creation

Creates a new user. Note only administrators can create new
users. Either `password`, `reset_password`, or `force_random_password`
must be specified. If `reset_password` and `force_random_password` are
both `false`, then `password` is required.

Note that `force_random_password` and `reset_password` take priority
over `password`. In addition, `reset_password` and
`force_random_password` can be used together.

NOTE: **Note:**
From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29888/), `private_profile` will default to `false`.

```
POST /users
```

Parameters:

- `email` (required)             - Email
- `password` (optional)          - Password
- `reset_password` (optional)    - Send user password reset link - true or false(default)
- `username` (required)          - Username
- `name` (required)              - Name
- `skype` (optional)             - Skype ID
- `linkedin` (optional)          - LinkedIn
- `twitter` (optional)           - Twitter account
- `website_url` (optional)       - Website URL
- `organization` (optional)      - Organization name
- `projects_limit` (optional)    - Number of projects user can create
- `extern_uid` (optional)        - External UID
- `provider` (optional)          - External provider name
- `bio` (optional)               - User's biography
- `location` (optional)          - User's location
- `public_email` (optional)      - The public email of the user
- `admin` (optional)             - User is admin - true or false (default)
- `can_create_group` (optional)  - User can create groups - true or false
- `skip_confirmation` (optional) - Skip confirmation - true or false (default)

- `external` (optional)          - Flags the user as external - true or false (default)

- `avatar` (optional)            - Image file for user's avatar

- `private_profile` (optional)   - User's profile is private - true or false (default)

- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**

## 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
- `organization`                   - Organization name
- `projects_limit`                 - Limit projects each user can create
- `extern_uid`                     - External UID
- `provider`                       - External provider name

- `group_id_for_saml` (optional)   - ID of group where SAML has been configured

- `bio`                            - User's biography
- `location` (optional)            - User's location
- `public_email` (optional)        - The public email of the user
- `admin` (optional)               - User is admin - true or false (default)
- `can_create_group` (optional)    - User can create groups - true or false

- `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)

- `external` (optional)            - Flags the user as external - true or false (default)

- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user

- `avatar` (optional)              - Image file for user's avatar

- `private_profile` (optional)     - User's profile is private - true or false (default)

- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**

- `note` (optional) - Admin notes for this user **(STARTER)**

On password update, user will be forced to change it upon next login.

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 returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.

```
DELETE /users/:id
```

Parameters:

- `id` (required) - The ID of the user

- `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.

## List current user (for normal users)

Gets currently authenticated 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",
  "bio": null,

  "location": null,

  "public_email": "john@example.com",

  "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,

  "last_activity_on": "2012-05-23",

  "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_profile": false

}
```

## List current user (for admins)

Parameters:

- `sudo` (optional) - the ID of a user to make the call in their place

```
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,

  "public_email": "john@example.com",

  "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,

  "last_activity_on": "2012-05-23",

  "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_profile": false

}
```

## User status

Get the status of the currently signed in user.

```
GET /user/status
```

```bash

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status"

```

Example response:

```json
{
  "emoji":"coffee",

  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>"

}
```

## Get the status of a user

Get the status of a user.

```
GET /users/:id_or_username/status
```

| Attribute        | Type   | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `id_or_username` | string | yes      | The id or username of the user to get a status of |

```bash
curl "https://gitlab.example.com/users/janedoe/status"
```

Example response:

```json
{
  "emoji":"coffee",

  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>"

}
```

## Set user status

Set the status of the current user.

```
PUT /user/status
```

| Attribute | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |

| `emoji`   | string | no     | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. |

| `message` | string | no     | The message to set as a status. It can also contain emoji codes. |

When both parameters `emoji` and `message` are empty, the status will be cleared.

```bash

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "emoji=coffee" --data "message=I crave coffee" https://gitlab.example.com/api/v4/user/status

```

Example responses

```json
{
  "emoji":"coffee",
  "message":"I crave coffee",
  "message_html": "I crave coffee"
}
```

## User counts

Get the counts (same as in top right menu) of the currently signed in user.

| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `merge_requests`   | number | Merge requests that are active and assigned to current user. |

```
GET /user_counts
```

```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"
```

Example response:

```json
{
  "merge_requests": 4
}
```

## List user projects

Please refer to the [List of user projects](projects.md#list-user-projects).

## 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",