diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 11:59:07 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 11:59:07 +0000 |
commit | 8b573c94895dc0ac0e1d9d59cf3e8745e8b539ca (patch) | |
tree | 544930fb309b30317ae9797a9683768705d664c4 /doc/api/users.md | |
parent | 4b1de649d0168371549608993deac953eb692019 (diff) | |
download | gitlab-ce-8b573c94895dc0ac0e1d9d59cf3e8745e8b539ca.tar.gz |
Add latest changes from gitlab-org/gitlab@13-7-stable-eev13.7.0-rc42
Diffstat (limited to 'doc/api/users.md')
-rw-r--r-- | doc/api/users.md | 101 |
1 files changed, 70 insertions, 31 deletions
diff --git a/doc/api/users.md b/doc/api/users.md index e1fa97765df..f73e1829024 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Users API @@ -54,7 +54,7 @@ GET /users?username=jack_smith ``` 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 active users +It does not support `active=false` or `blocked=false`. The list of billable users is the total number of users minus the blocked users. ```plaintext @@ -65,7 +65,7 @@ GET /users?active=true GET /users?blocked=true ``` -GitLab supports bot users such as the [alert bot](../operations/incident_management/generic_alerts.md) +GitLab supports bot users such as the [alert bot](../operations/incident_management/alert_integrations.md) or the [support bot](../user/project/service_desk.md#support-bot-user). To exclude these users from the users' list, you can use the parameter `exclude_internal=true` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4). @@ -74,7 +74,7 @@ To exclude these users from the users' list, you can use the parameter `exclude_ GET /users?exclude_internal=true ``` -NOTE: **Note:** +NOTE: Username search is case insensitive. ### For admins @@ -170,7 +170,7 @@ GET /users ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `using_license_seat` parameters. ```json [ @@ -179,12 +179,13 @@ Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) ... "shared_runners_minutes_limit": 133, "extra_shared_runners_minutes_limit": 133, + "using_license_seat": true ... } ] ``` -Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option: ```json @@ -332,10 +333,10 @@ Example Responses: } ``` -NOTE: **Note:** +NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -348,7 +349,7 @@ the `shared_runners_minutes_limit`, and `extra_shared_runners_minutes_limit` par } ``` -Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also +Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option: ```json @@ -384,11 +385,11 @@ 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-foss/-/merge_requests/29888/), `private_profile` will default to `false`. +NOTE: +From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29888/), `private_profile` defaults to `false`. -NOTE: **Note:** -From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` will default to `""` instead of `null`. +NOTE: +From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` defaults to `""` instead of `null`. ```plaintext POST /users @@ -415,7 +416,7 @@ Parameters: | `note` | No | Admin notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (will be converted to false) | +| `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | | `projects_limit` | No | Number of projects user can create | | `provider` | No | External provider name | | `public_email` | No | The public email of the user | @@ -457,7 +458,7 @@ Parameters: | `note` | No | Admin notes for this user | | `organization` | No | Organization name | | `password` | No | Password | -| `private_profile` | No | User's profile is private - true, false (default), or null (will be converted to false) | +| `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 | @@ -469,7 +470,7 @@ Parameters: | `username` | No | Username | | `website_url` | No | Website URL | -On password update, user will be forced to change it upon next login. +On password update, the user is 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. For example, when renaming the email address to some existing one. @@ -501,7 +502,7 @@ 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. + are deleted instead, as well as groups owned solely by this user. ## List current user (for normal users) @@ -664,7 +665,7 @@ PUT /user/status | `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. | -When both parameters `emoji` and `message` are empty, the status will be cleared. +When both parameters `emoji` and `message` are empty, the status is cleared. ```shell 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" @@ -792,7 +793,7 @@ Parameters: } ``` -Will return created key with status `201 Created` on success. If an +Returns a 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 @@ -823,7 +824,7 @@ Parameters: - `key` (required) - new SSH key - `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) -NOTE: **Note:** +NOTE: This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)** ## Delete SSH key for current user @@ -1068,7 +1069,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Get a list of currently authenticated user's emails. -NOTE: **Note:** +NOTE: Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently does not return the primary email address. @@ -1097,7 +1098,7 @@ Parameters: Get a list of a specified user's emails. Available only for admin -NOTE: **Note:** +NOTE: Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently does not return the primary email address. @@ -1147,7 +1148,7 @@ Parameters: } ``` -Will return created email with status `201 Created` on success. If an +Returns a created email with status `201 Created` on success. If an error occurs a `400 Bad Request` is returned with a message explaining the error: ```json @@ -1232,7 +1233,7 @@ Parameters: - `id` (required) - ID of specified user -Will return `201 OK` on success, `404 User Not Found` is user cannot be found or +Returns `201 OK` on success, `404 User Not Found` is user cannot be found or `403 Forbidden` when trying to unblock a user blocked by LDAP synchronization. ## Deactivate user @@ -1275,8 +1276,8 @@ Parameters: Returns: - `201 OK` on success. -- `404 User Not Found` if user cannot be found. -- `403 Forbidden` when trying to activate a user blocked by admin or by LDAP synchronization. +- `404 User Not Found` if the user cannot be found. +- `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization. ### Get user contribution events @@ -1337,6 +1338,44 @@ Example response: ] ``` +## Approve user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263107) in GitLab 13.7. + +Approves the specified user. Available only for administrators. + +```plaintext +POST /users/:id/approve +``` + +Parameters: + +- `id` (required) - ID of specified user + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve" +``` + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if user cannot be found. +- `403 Forbidden` if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization. + +Example Responses: + +```json +{ "message": "Success" } +``` + +```json +{ "message": "404 User Not Found" } +``` + +```json +{ "message": "The user you are trying to approve is not pending an approval" } +``` + ## Get an impersonation token of a user > Requires admin permissions. @@ -1379,11 +1418,11 @@ Example response: ## Create an impersonation token > Requires admin permissions. -> Token values are returned once. Make sure you save it - you won't be able to access it again. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new impersonation token. Note that only administrators can do this. 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 their profile +both API calls and Git reads and writes. The user can't see these tokens in their profile settings page. ```plaintext @@ -1447,11 +1486,11 @@ Parameters: > - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-an-administrators-ability-to-use-the-api-to-create-personal-access-tokens). **(CORE)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. > Requires admin permissions. -> Token values are returned once. Make sure you save it - you won't be able to access it again. +> Token values are returned once. Make sure you save it - you can't access it again. It creates a new personal access token. @@ -1490,7 +1529,7 @@ Example response: ## Get user activities (admin only) -NOTE: **Note:** +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. |