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.md101
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.
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-14 22:44:41 +0300