Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/doc/api/users.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/users.md')
-rw-r--r--doc/api/users.md164
1 files changed, 103 insertions, 61 deletions
diff --git a/doc/api/users.md b/doc/api/users.md
index 5e41a0f6258..06c0fadbbbf 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -57,8 +57,7 @@ NOTE:
Username search is case insensitive.
In addition, you can filter users based on the states `blocked` and `active`.
-It does not support `active=false` or `blocked=false`. The list of billable users
-is the total number of users minus the blocked users.
+It does not support `active=false` or `blocked=false`.
```plaintext
GET /users?active=true
@@ -105,7 +104,7 @@ parameter `without_project_bots=true`.
GET /users?without_project_bots=true
```
-### For administrators
+### For administrators **(FREE SELF)**
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
@@ -284,7 +283,7 @@ Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | ID of a user |
```json
{
@@ -314,7 +313,7 @@ Parameters:
}
```
-### For administrator
+### For administrators **(FREE SELF)**
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
@@ -326,7 +325,7 @@ Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | ID of a user |
Example Responses:
@@ -477,7 +476,7 @@ Parameters:
| `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. |
| `skip_confirmation` | No | Skip confirmation - true or false (default) |
| `skype` | No | Skype ID |
-| `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) |
+| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) |
| `twitter` | No | Twitter account |
| `username` | Yes | Username |
| `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page |
@@ -507,7 +506,7 @@ Parameters:
| `external` | No | Flags the user as external - true or false (default) |
| `extra_shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. |
| `group_id_for_saml` | No | ID of group where SAML has been configured |
-| `id` | Yes | The ID of the user |
+| `id` | Yes | ID of the user |
| `linkedin` | No | LinkedIn |
| `location` | No | User's location |
| `name` | No | Name |
@@ -517,11 +516,11 @@ Parameters:
| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) |
| `projects_limit` | No | Limit projects each user can create |
| `provider` | No | External provider name |
-| `public_email` | No | The public email of the user (must be already verified) |
+| `public_email` | No | Public email of the user (must be already verified) |
| `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. |
| `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) |
| `skype` | No | Skype ID |
-| `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) |
+| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) |
| `twitter` | No | Twitter account |
| `username` | No | Username |
| `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page |
@@ -544,7 +543,7 @@ Parameters:
| Attribute | Type | Required | Description |
|------------|---------|----------|------------------------|
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | ID of a user |
| `provider` | string | yes | External provider name |
## User deletion
@@ -560,10 +559,14 @@ Parameters:
| Attribute | Type | Required | Description |
|---------------|---------|----------|----------------------------------------------|
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | ID of a user |
| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. |
-## List current user (for normal users)
+## List current user
+
+Get current user.
+
+### For normal users
Gets currently authenticated user.
@@ -619,7 +622,7 @@ GET /user
Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters.
-## List current user (for administrators)
+### For administrators **(FREE SELF)**
> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10.
@@ -631,7 +634,7 @@ Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|--------------------------------------------------|
-| `sudo` | integer | no | the ID of a user to make the call in their place |
+| `sudo` | integer | no | ID of a user to make the call in their place |
```json
{
@@ -696,7 +699,7 @@ GET /user/status
```
```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status"
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/status"
```
Example response:
@@ -721,7 +724,7 @@ 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 |
+| `id_or_username` | string | yes | ID or username of the user to get a status of |
```shell
curl "https://gitlab.example.com/users/janedoe/status"
@@ -749,8 +752,8 @@ 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](https://github.com/bonusly/gemojione/blob/master/config/index.json). |
-| `message` | string | no | The message to set as a status. It can also contain emoji codes. |
+| `emoji` | string | no | 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](https://github.com/bonusly/gemojione/blob/master/config/index.json). |
+| `message` | string | no | Message to set as a status. It can also contain emoji codes. |
| `clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes`, `3_hours`, `8_hours`, `1_day`, `3_days`, `7_days`, `30_days`
When both parameters `emoji` and `message` are empty, the status is cleared. When the `clear_status_after` parameter is missing from the request, the previously set value for `"clear_status_after` is cleared.
@@ -818,7 +821,7 @@ Parameters:
| `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. |
| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. |
-## User Follow
+## User follow
### Follow and unfollow users
@@ -836,7 +839,7 @@ POST /users/:id/unfollow
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------- |
-| `id` | integer | yes | The ID of the user to follow |
+| `id` | integer | yes | ID of the user to follow |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow"
@@ -871,7 +874,7 @@ GET /users/:id/following
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------- |
-| `id` | integer | yes | The ID of the user to follow |
+| `id` | integer | yes | ID of the user to follow |
```shell
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/followers"
@@ -975,7 +978,7 @@ GET /users/:id_or_username/keys
| Attribute | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------------- |
-| `id_or_username` | string | yes | The ID or username of the user to get the SSH keys for. |
+| `id_or_username` | string | yes | ID or username of the user to get the SSH keys for. |
## Single SSH key
@@ -989,7 +992,7 @@ Parameters:
| Attribute | Type | Required | Description |
|-----------|--------|----------|----------------------|
-| `key_id` | string | yes | The ID of an SSH key |
+| `key_id` | string | yes | ID of an SSH key |
```json
{
@@ -1038,9 +1041,9 @@ Parameters:
| Attribute | Type | Required | Description |
|--------------|--------|----------|--------------------------------------------------------------------------------|
-| `title` | string | yes | new SSH key's title |
-| `key` | string | yes | new SSH key |
-| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
+| `title` | string | yes | New SSH key's title |
+| `key` | string | yes | New SSH key |
+| `expires_at` | string | no | Expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
```json
{
@@ -1079,9 +1082,9 @@ Parameters:
| Attribute | Type | Required | Description |
|--------------|---------|----------|--------------------------------------------------------------------------------|
| `id` | integer | yes | ID of specified user |
-| `title` | string | yes | new SSH key's title |
-| `key` | string | yes | new SSH key |
-| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
+| `title` | string | yes | New SSH key's title |
+| `key` | string | yes | New SSH key |
+| `expires_at` | string | no | Expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
NOTE:
This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)**
@@ -1152,7 +1155,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
-| `key_id` | integer | yes | The ID of the GPG key |
+| `key_id` | integer | yes | ID of the GPG key |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"
@@ -1180,7 +1183,7 @@ Parameters:
| Attribute | Type | Required | Description |
|-----------|--------|----------|-----------------|
-| `key` | string | yes | The new GPG key |
+| `key` | string | yes | New GPG key |
```shell
curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
@@ -1211,7 +1214,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
-| `key_id` | integer | yes | The ID of the GPG key |
+| `key_id` | integer | yes | ID of the GPG key |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"
@@ -1231,7 +1234,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------ |
-| `id` | integer | yes | The ID of the user |
+| `id` | integer | yes | ID of the user |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys"
@@ -1262,8 +1265,8 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
-| `id` | integer | yes | The ID of the user |
-| `key_id` | integer | yes | The ID of the GPG key |
+| `id` | integer | yes | ID of the user |
+| `key_id` | integer | yes | ID of the GPG key |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"
@@ -1291,8 +1294,8 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
-| `id` | integer | yes | The ID of the user |
-| `key_id` | integer | yes | The ID of the GPG key |
+| `id` | integer | yes | ID of the user |
+| `key_id` | integer | yes | ID of the GPG key |
```shell
curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
@@ -1323,8 +1326,8 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
-| `id` | integer | yes | The ID of the user |
-| `key_id` | integer | yes | The ID of the GPG key |
+| `id` | integer | yes | ID of the user |
+| `key_id` | integer | yes | ID of the GPG key |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"
@@ -1627,8 +1630,8 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ---------------------------------------------------------- |
-| `user_id` | integer | yes | The ID of the user |
-| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) |
+| `user_id` | integer | yes | ID of the user |
+| `state` | string | no | Filter tokens based on state (`all`, `active`, `inactive`) |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"
@@ -1761,8 +1764,8 @@ Parameters:
| Attribute | Type | Required | Description |
| ------------------------ | ------- | -------- | --------------------------------- |
-| `user_id` | integer | yes | The ID of the user |
-| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
+| `user_id` | integer | yes | ID of the user |
+| `impersonation_token_id` | integer | yes | ID of the impersonation token |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2"
@@ -1802,10 +1805,10 @@ POST /users/:user_id/impersonation_tokens
| Attribute | Type | Required | Description |
| ------------ | ------- | -------- | --------------------------------------------------------------------------- |
-| `user_id` | integer | yes | The ID of the user |
-| `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`) |
+| `user_id` | integer | yes | ID of the user |
+| `name` | string | yes | Name of the impersonation token |
+| `expires_at` | date | no | Expiration date of the impersonation token in ISO format (`YYYY-MM-DD`) |
+| `scopes` | array | yes | Array of scopes of the impersonation token (`api`, `read_user`) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
@@ -1845,8 +1848,8 @@ Parameters:
| Attribute | Type | Required | Description |
| ------------------------ | ------- | -------- | --------------------------------- |
-| `user_id` | integer | yes | The ID of the user |
-| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
+| `user_id` | integer | yes | ID of the user |
+| `impersonation_token_id` | integer | yes | ID of the impersonation token |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
@@ -1867,10 +1870,10 @@ POST /users/:user_id/personal_access_tokens
| Attribute | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `user_id` | integer | yes | The ID of the user |
-| `name` | string | yes | The name of the personal access token |
-| `expires_at` | date | no | The expiration date of the personal access token in ISO format (`YYYY-MM-DD`) |
-| `scopes` | array | yes | The array of scopes of the personal access token. See [personal access token scopes](../user/profile/personal_access_tokens.md#personal-access-token-scopes) for possible values. |
+| `user_id` | integer | yes | ID of the user |
+| `name` | string | yes | Name of the personal access token |
+| `expires_at` | date | no | Expiration date of the personal access token in ISO format (`YYYY-MM-DD`) |
+| `scopes` | array | yes | Array of scopes of the personal access token. See [personal access token scopes](../user/profile/personal_access_tokens.md#personal-access-token-scopes) for possible values. |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
@@ -1895,10 +1898,11 @@ Example response:
}
```
-## Get user activities (administrator only)
+## Get user activities
-NOTE:
-This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
+Pre-requisite:
+
+- You must be an administrator.
Get the last activity date for all users, sorted from oldest to newest.
@@ -1921,7 +1925,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
-| `from` | string | no | Date string in the format YEAR-MONTH-DAY. For example, `2016-03-11`. Defaults to 6 months ago. |
+| `from` | string | no | Date string in the format `YEAR-MM-DD`. For example, `2016-03-11`. Defaults to 6 months ago. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/activities"
@@ -1951,11 +1955,15 @@ Example response:
`last_activity_at` is deprecated. Use `last_activity_on` instead.
-## User memberships (administrator only)
+## User memberships
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20532) in GitLab 12.8.
-Lists all projects and groups a user is a member of. This endpoint is available for administrators only.
+Pre-requisite:
+
+- You must be an administrator.
+
+Lists all projects and groups a user is a member of.
It returns the `source_id`, `source_name`, `source_type` and `access_level` of a membership.
Source can be of type `Namespace` (representing a group) or `Project`. The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included.
Access levels are represented by an integer value. For more details, read about the meaning of [access level values](access_requests.md#valid-access-levels).
@@ -1968,7 +1976,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------ |
-| `id` | integer | yes | The ID of a specified user |
+| `id` | integer | yes | ID of a specified user |
| `type` | string | no | Filter memberships by type. Can be either `Project` or `Namespace` |
Returns:
@@ -2000,3 +2008,37 @@ Example response:
}
]
```
+
+## Disable two factor authentication
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2.
+
+Pre-requisite:
+
+- You must be an administrator.
+
+Disables two factor authentication (2FA) for the specified user.
+
+Administrators cannot disable 2FA for their own user account or other administrators using the API. Instead, they can disable an
+administrator's 2FA [using the Rails console](../security/two_factor_authentication.md#for-a-single-user).
+
+```plaintext
+PATCH /users/:id/disable_two_factor
+```
+
+Parameters:
+
+| Attribute | Type | Required | Description |
+| --------- | ------- | -------- | --------------------- |
+| `id` | integer | yes | ID of the user |
+
+```shell
+curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1/disable_two_factor"
+```
+
+Returns:
+
+- `204 No content` on success.
+- `400 Bad request` if two factor authentication is not enabled for the specified user.
+- `403 Forbidden` if not authenticated as an administrator.
+- `404 User Not Found` if user cannot be found.
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-31 08:07:44 +0300