diff --git a/doc/administration/admin_area.md b/doc/administration/admin_area.md index 8a8afb56b15e374c2f19825923e5a4bde3937df1..50f342718ce6e581cf02c8988f5f448df7fd5eaa 100644 --- a/doc/administration/admin_area.md +++ b/doc/administration/admin_area.md @@ -179,7 +179,7 @@ The following data is included in the export: - Type - Path - Access level ([Project](../user/permissions.md#project-members-permissions) and [Group](../user/permissions.md#group-members-permissions)) -- Date of last activity. For a list of activities that populate this column, see the [Users API documentation](../api/users.md#get-user-activities). +- Date of last activity. For a list of activities that populate this column, see the [Users API documentation](../api/users.md#get-a-list-of-a-users-activity). Only the first 100,000 user accounts are exported. diff --git a/doc/api/users.md b/doc/api/users.md index 2e5df9bbed4977413cf3d8fe73f4f82890e8511e..9c8738ab1483cbfbceeb5b5c0df80287b99e7865 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -10,9 +10,8 @@ DETAILS: **Tier:** Free, Premium, Ultimate **Offering:** GitLab.com, Self-managed, GitLab Dedicated -This documentation has information on API calls, parameters and responses for the Users API. - -For information on user activities that update the user event timestamps, see [get user activities](#get-user-activities). +You can [manage your account](../user/profile/index.md) and +[manage other users](../user/profile/account/create_accounts.md) by using the REST API. ## List users @@ -880,9 +879,13 @@ parameters: - `provisioned_by_group_id` - `using_license_seat` -## Get user status +## Get your user status + +Get your user status. -Get the status of the authenticated user. +Prerequisites: + +- You must be authenticated. ```plaintext GET /user/status @@ -938,9 +941,13 @@ Example response: } ``` -## Set user status +## Set your user status -Set the status of the current user. +Set your user status. + +Prerequisites: + +- You must be authenticated. ```plaintext PUT /user/status @@ -955,10 +962,10 @@ Supported attributes: | `message` | string | no | Message to set as a status. It can also contain emoji codes. Cannot exceed 100 characters. | | `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` | -Difference between `PUT` and `PATCH` +Difference between `PUT` and `PATCH`: -When using `PUT` any parameters that are not passed are set to `null` and therefore cleared. When using `PATCH` any -parameters that are not passed are ignored. Explicitly pass `null` to clear a field. +- When using `PUT` any parameters that are not passed are set to `null` and therefore cleared. +- When using `PATCH` any parameters that are not passed are ignored. Explicitly pass `null` to clear a field. Example request: @@ -978,9 +985,13 @@ Example response: } ``` -## Get user preferences +## Get your user preferences -Get a list of the authenticated user's preferences. +Get your user preferences. + +Prerequisites: + +- You must be authenticated. ```plaintext GET /user/preferences @@ -998,9 +1009,13 @@ Example response: } ``` -## User preference modification +## Update your user preferences + +Update your user preferences. + +Prerequisites: -Update the current user's preferences. +- You must be authenticated. ```plaintext PUT /user/preferences @@ -1024,12 +1039,12 @@ Supported attributes: | `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | | `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see [Token Payload](../ci/secrets/id_token_authentication.md#token-payload). | -## User follow +## User following You can [follow and unfollow a user](../user/profile/index.md#follow-users) by using the REST API. You can also get the details of who a user is following, and who is following them. -### Follow and unfollow a user +### Follow a user Follow a user. @@ -1037,12 +1052,6 @@ Follow a user. POST /users/:id/follow ``` -Unfollow a user. - -```plaintext -POST /users/:id/unfollow -``` - Supported attributes: | Attribute | Type | Required | Description | @@ -1069,25 +1078,39 @@ Example response: } ``` -### Get details of followers of a user and who's following them +### Unfollow a user -Get the followers of a user. +Unfollow a user. ```plaintext -GET /users/:id/followers +POST /users/:id/unfollow +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:------------| +| `id` | integer | yes | ID of the user to unfollow | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/unfollow" ``` -Get the list of users being followed. +### Get the followers of a user + +Get the followers of a user. ```plaintext -GET /users/:id/following +GET /users/:id/followers ``` Supported attributes: | Attribute | Type | Required | Description | |:----------|:--------|:---------|:------------| -| `id` | integer | yes | ID of the user to follow | +| `id` | integer | yes | ID of the user | Example request: @@ -1120,9 +1143,33 @@ Example response: ] ``` -## User counts +### Get the users that a user is following -Get the counts (same as in the upper-left menu) of the authenticated user. +Get the list of users being followed by a user. + +```plaintext +GET /users/:id/following +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:------------| +| `id` | integer | yes | ID of the user | + +Example request: + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/following" +``` + +## Get a count of your assigned issues, merge requests, and reviews + +Get a count of your assigned issues, merge requests, and reviews. + +Prerequisites: + +- You must be authenticated. Supported attributes: @@ -1156,13 +1203,9 @@ Example response: } ``` -## List user projects - -See the [list of user projects](projects.md#list-a-users-projects). +## Get a count of a user's projects, groups, issues, and merge requests -## List associations count for user - -Get a list of a specified user's count of: +Get a list of a user's count of: - Projects. - Groups. @@ -1192,7 +1235,7 @@ Example response: } ``` -## Get user activities +## Get a list of a user's activity DETAILS: **Tier:** Free, Premium, Ultimate @@ -1255,13 +1298,13 @@ Example response: `last_activity_at` is deprecated. Use `last_activity_on` instead. -## User memberships +## Get a list of projects and groups that a user is a member of DETAILS: **Tier:** Free, Premium, Ultimate **Offering:** Self-managed, GitLab Dedicated -Pre-requisite: +Prerequisites: - You must be an administrator. @@ -1314,7 +1357,7 @@ Returns: - `403 Forbidden` when not requested by an administrator. - `400 Bad Request` when requested type is not supported. -## Disable two-factor authentication +## Disable two-factor authentication for a user DETAILS: **Tier:** Free, Premium, Ultimate @@ -1322,7 +1365,7 @@ DETAILS: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2. -Pre-requisite: +Prerequisites: - You must be an administrator. @@ -1408,11 +1451,15 @@ Example response: } ``` -## Upload a current user avatar +## Upload an avatar for yourself > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0. -Upload an avatar to current user. +Upload an avatar for yourself. + +Prerequisites: + +- You must be authenticated. ```plaintext PUT /user/avatar diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 1935a91a0c045d733f1eb5316f6742c92e2b3084..6301520f5369f8ba8b5f32b7876999f391e61098 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -172,7 +172,7 @@ The administrator is notified that 2FA has been disabled. #### Non-administrators In GitLab 15.2 and later, you can use either the Rails console or the -[API endpoint](../api/users.md#disable-two-factor-authentication) to disable 2FA +[API endpoint](../api/users.md#disable-two-factor-authentication-for-a-user) to disable 2FA for a non-administrator. You can disable 2FA for your own account. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index a07ca4eb55bf9984b77a045fef905a8a8e35f41f..965187634a573c206e459f243b4c75a828b5d4d7 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -244,7 +244,7 @@ To set your current status: 1. Select a value from the **Clear status after** dropdown list. 1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. -You can also set your current status from [your user settings](#access-your-user-settings) or by [using the API](../../api/users.md#get-user-status). +You can also set your current status from [your user settings](#access-your-user-settings) or by [using the API](../../api/users.md#set-your-user-status). If you select the **Busy** checkbox, remember to clear it when you become available again.