diff options
Diffstat (limited to 'doc/api/users.md')
-rw-r--r-- | doc/api/users.md | 74 |
1 files changed, 56 insertions, 18 deletions
diff --git a/doc/api/users.md b/doc/api/users.md index e1fa97765df..c4774dbdfb4 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -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 @@ -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`, and `extra_shared_runners_minutes_limit` parameters. ```json [ @@ -184,7 +184,7 @@ Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) ] ``` -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 @@ -335,7 +335,7 @@ Example Responses: 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 +348,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 @@ -385,10 +385,10 @@ 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`. +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`. +From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35604), `bio` defaults to `""` instead of `null`. ```plaintext POST /users @@ -469,7 +469,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 +501,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 +664,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 +792,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 @@ -1147,7 +1147,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 +1232,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 +1275,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 +1337,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 +1417,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 @@ -1451,7 +1489,7 @@ CAUTION: **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. |