From fcad7ec86b2295e81549e716f8296a0a615815ba Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Tue, 22 Oct 2024 14:41:11 -0700
Subject: [PATCH] [OpenAPI] Edit more security API summaries (#3036)

---
 specification/_doc_ids/table.csv                         | 2 ++
 .../SecurityGetUserPrivilegesRequest.ts                  | 1 +
 specification/security/get_user_profile/Request.ts       | 4 +++-
 .../security/grant_api_key/SecurityGrantApiKeyRequest.ts | 6 ++++--
 .../has_privileges/SecurityHasPrivilegesRequest.ts       | 4 +++-
 .../security/has_privileges_user_profile/Request.ts      | 4 ++++
 .../SecurityInvalidateApiKeyRequest.ts                   | 6 ++++--
 .../invalidate_token/SecurityInvalidateTokenRequest.ts   | 8 ++++++++
 .../put_privileges/SecurityPutPrivilegesRequest.ts       | 3 ++-
 .../security/put_role/SecurityPutRoleRequest.ts          | 6 +++++-
 .../put_role_mapping/SecurityPutRoleMappingRequest.ts    | 9 +++++++++
 .../security/put_user/SecurityPutUserRequest.ts          | 4 ++++
 .../security/query_api_keys/QueryApiKeysRequest.ts       | 5 +++--
 specification/security/query_role/QueryRolesRequest.ts   | 4 +++-
 .../security/query_user/SecurityQueryUserRequest.ts      | 5 ++++-
 specification/security/saml_authenticate/Request.ts      | 4 +++-
 specification/security/saml_complete_logout/Request.ts   | 2 ++
 specification/security/saml_invalidate/Request.ts        | 2 ++
 specification/security/saml_logout/Request.ts            | 2 ++
 .../security/saml_prepare_authentication/Request.ts      | 4 +++-
 .../security/saml_service_provider_metadata/Request.ts   | 2 ++
 specification/security/suggest_user_profiles/Request.ts  | 2 ++
 specification/security/update_api_key/Request.ts         | 1 +
 .../security/update_user_profile_data/Request.ts         | 4 +++-
 24 files changed, 79 insertions(+), 15 deletions(-)

diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index ca10e4db2..5a9d830cf 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -111,6 +111,7 @@ data-stream-path-param,https://www.elastic.co/guide/en/elasticsearch/reference/{
 data-streams,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/data-streams.html
 date-index-name-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/date-index-name-processor.html
 dcg,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-rank-eval.html#_discounted_cumulative_gain_dcg
+defining-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/defining-roles.html
 delete-async-sql-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html
 delete-enrich-policy-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-enrich-policy-api.html
 delete-license,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-license.html
@@ -612,6 +613,7 @@ uppercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 urldecode-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/urldecode-processor.html
 usage-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/usage-api.html
 user-agent-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-agent-processor.html
+user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/user-profile.html
 voting-config-exclusions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html
 watcher-api-ack-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-ack-watch.html
 watcher-api-activate-watch,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/watcher-api-activate-watch.html
diff --git a/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts b/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts
index 07c3d9a54..a549b6f18 100644
--- a/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts
+++ b/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Get user privileges.
  * @rest_spec_name security.get_user_privileges
  * @availability stack since=6.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/get_user_profile/Request.ts b/specification/security/get_user_profile/Request.ts
index b65916328..81cd5a3a6 100644
--- a/specification/security/get_user_profile/Request.ts
+++ b/specification/security/get_user_profile/Request.ts
@@ -21,7 +21,9 @@ import { UserProfileId } from '@security/_types/UserProfile'
 import { RequestBase } from '@_types/Base'
 
 /**
- * Retrieves a user's profile using the unique profile ID.
+ * Get a user profile.
+ *
+ * Get a user's profile using the unique profile ID.
  * @rest_spec_name security.get_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts b/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts
index 60690cc00..30e747820 100644
--- a/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts
+++ b/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts
@@ -22,8 +22,10 @@ import { Password, Username } from '@_types/common'
 import { ApiKeyGrantType, GrantApiKey } from './types'
 
 /**
- * Creates an API key on behalf of another user.
- * This API is similar to Create API keys, however it creates the API key for a user that is different than the user that runs the API.
+ * Grant an API key.
+ *
+ * Create an API key on behalf of another user.
+ * This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.
  * The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created.
  * It is not possible to use this API to create an API key without that user’s credentials.
  * The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user.
diff --git a/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts b/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts
index ee25210b7..560746e54 100644
--- a/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts
+++ b/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts
@@ -24,10 +24,12 @@ import { ApplicationPrivilegesCheck, IndexPrivilegesCheck } from './types'
 
 /**
  * Check user privileges.
- * Determines whether the specified user has a specified list of privileges.
+ *
+ * Determine whether the specified user has a specified list of privileges.
  * @rest_spec_name security.has_privileges
  * @availability stack since=6.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/has_privileges_user_profile/Request.ts b/specification/security/has_privileges_user_profile/Request.ts
index d8487d4c1..7f6a6d4ea 100644
--- a/specification/security/has_privileges_user_profile/Request.ts
+++ b/specification/security/has_privileges_user_profile/Request.ts
@@ -22,10 +22,14 @@ import { RequestBase } from '@_types/Base'
 import { PrivilegesCheck } from './types'
 
 /**
+ * Check user profile privileges.
+ *
+ * Determine whether the users associated with the specified user profile IDs have all the requested privileges.
  * @rest_spec_name security.has_privileges_user_profile
  * @availability stack since=8.3.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_user_profile
+ * @ext_doc_id user-profile
  */
 export interface Request extends RequestBase {
   body: {
diff --git a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts
index 438ce3576..96c1f01c2 100644
--- a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts
+++ b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts
@@ -22,13 +22,15 @@ import { Id, Name, Username } from '@_types/common'
 
 /**
  * Invalidate API keys.
- * Invalidates one or more API keys.
+ *
+ * This API invalidates API keys created by the create API key or grant API key APIs.
+ * Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.
  * The `manage_api_key` privilege allows deleting any API keys.
  * The `manage_own_api_key` only allows deleting API keys that are owned by the user.
  * In addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:
  * - Set the parameter `owner=true`.
  * - Or, set both `username` and `realm_name` to match the user’s identity.
- * - Or, if the request is issued by an API key, i.e. an API key invalidates itself, specify its ID in the `ids` field.
+ * - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.
  * @rest_spec_name security.invalidate_api_key
  * @availability stack since=6.7.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts b/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts
index 0a7f71ef0..0e1ef59e2 100644
--- a/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts
+++ b/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts
@@ -21,6 +21,14 @@ import { RequestBase } from '@_types/Base'
 import { Name, Username } from '@_types/common'
 
 /**
+ * Invalidate a token.
+ *
+ * The access tokens returned by the get token API have a finite period of time for which they are valid.
+ * After that time period, they can no longer be used.
+ * The time period is defined by the `xpack.security.authc.token.timeout` setting.
+ *
+ * The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once.
+ * If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.
  * @rest_spec_name security.invalidate_token
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts b/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts
index ea5414d53..90c7694e4 100644
--- a/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts
+++ b/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts
@@ -23,10 +23,11 @@ import { Refresh } from '@_types/common'
 import { Actions } from './types'
 
 /**
+ * Create or update application privileges.
  * @rest_spec_name security.put_privileges
  * @availability stack since=6.4.0 stability=stable
  * @availability serverless stability=stable visibility=private
- *
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {
   query_parameters: {
diff --git a/specification/security/put_role/SecurityPutRoleRequest.ts b/specification/security/put_role/SecurityPutRoleRequest.ts
index bfe818361..3aa4f673e 100644
--- a/specification/security/put_role/SecurityPutRoleRequest.ts
+++ b/specification/security/put_role/SecurityPutRoleRequest.ts
@@ -29,12 +29,16 @@ import { RequestBase } from '@_types/Base'
 import { Metadata, Name, Refresh } from '@_types/common'
 
 /**
- * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
+ * Create or update roles.
+ *
+ * The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management.
  * The create or update roles API cannot update roles that are defined in roles files.
+ * File-based role management is not available in Elastic Serverless.
  * @rest_spec_name security.put_role
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_security
+ * @ext_doc_id defining-roles
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts b/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts
index 2ad9aba1e..4061546c0 100644
--- a/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts
+++ b/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts
@@ -23,9 +23,18 @@ import { RequestBase } from '@_types/Base'
 import { Metadata, Name, Refresh } from '@_types/common'
 
 /**
+ * Create or update role mappings.
+ *
+ * Role mappings define which roles are assigned to each user.
+ * Each mapping has rules that identify users and a list of roles that are granted to those users.
+ * The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.
+ *
+ * This API does not create roles. Rather, it maps users to existing roles.
+ * Roles can be created by using the create or update roles API or roles files.
  * @rest_spec_name security.put_role_mapping
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id mapping-roles
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/put_user/SecurityPutUserRequest.ts b/specification/security/put_user/SecurityPutUserRequest.ts
index ada08b3c1..7e366a698 100644
--- a/specification/security/put_user/SecurityPutUserRequest.ts
+++ b/specification/security/put_user/SecurityPutUserRequest.ts
@@ -21,6 +21,10 @@ import { RequestBase } from '@_types/Base'
 import { Metadata, Password, Refresh, Username } from '@_types/common'
 
 /**
+ * Create or update users.
+ *
+ * A password is required for adding a new user but is optional when updating an existing user.
+ * To change a user’s password without updating any other fields, use the change password API.
  * @rest_spec_name security.put_user
  * @availability stack stability=stable
  */
diff --git a/specification/security/query_api_keys/QueryApiKeysRequest.ts b/specification/security/query_api_keys/QueryApiKeysRequest.ts
index 74ffb932b..363182881 100644
--- a/specification/security/query_api_keys/QueryApiKeysRequest.ts
+++ b/specification/security/query_api_keys/QueryApiKeysRequest.ts
@@ -24,8 +24,9 @@ import { Sort, SortResults } from '@_types/sort'
 import { ApiKeyAggregationContainer, ApiKeyQueryContainer } from './types'
 
 /**
- * Query API keys.
- * Retrieves a paginated list of API keys and their information. You can optionally filter the results with a query.
+ * Find API keys with a query.
+ *
+ * Get a paginated list of API keys and their information. You can optionally filter the results with a query.
  * @rest_spec_name security.query_api_keys
  * @availability stack since=7.15.0 stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/security/query_role/QueryRolesRequest.ts b/specification/security/query_role/QueryRolesRequest.ts
index 63fce15d6..9d0a93dde 100644
--- a/specification/security/query_role/QueryRolesRequest.ts
+++ b/specification/security/query_role/QueryRolesRequest.ts
@@ -23,7 +23,9 @@ import { Sort, SortResults } from '@_types/sort'
 import { RoleQueryContainer } from './types'
 
 /**
- * Retrieves roles in a paginated manner. You can optionally filter the results with a query.
+ * Find roles with a query.
+ *
+ * Get roles in a paginated manner. You can optionally filter the results with a query.
  * @rest_spec_name security.query_role
  * @availability stack since=8.15.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/query_user/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts
index e48823cdf..e567ed96a 100644
--- a/specification/security/query_user/SecurityQueryUserRequest.ts
+++ b/specification/security/query_user/SecurityQueryUserRequest.ts
@@ -23,7 +23,10 @@ import { Sort, SortResults } from '@_types/sort'
 import { UserQueryContainer } from './types'
 
 /**
- * Retrieves information for Users in a paginated manner. You can optionally filter the results with a query.
+ * Find users with a query.
+ *
+ * Get information for users in a paginated manner.
+ * You can optionally filter the results with a query.
  * @rest_spec_name security.query_user
  * @availability stack since=8.14.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/saml_authenticate/Request.ts b/specification/security/saml_authenticate/Request.ts
index 301cc098f..f3361e17e 100644
--- a/specification/security/saml_authenticate/Request.ts
+++ b/specification/security/saml_authenticate/Request.ts
@@ -21,7 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Submits a SAML Response message to Elasticsearch for consumption.
+ * Authenticate SAML.
+ *
+ * Submits a SAML response message to Elasticsearch for consumption.
  * @rest_spec_name security.saml_authenticate
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/saml_complete_logout/Request.ts b/specification/security/saml_complete_logout/Request.ts
index a5cbedec3..f85e46086 100644
--- a/specification/security/saml_complete_logout/Request.ts
+++ b/specification/security/saml_complete_logout/Request.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
+ * Logout of SAML completely.
+ *
  * Verifies the logout response sent from the SAML IdP.
  * @rest_spec_name security.saml_complete_logout
  * @availability stack since=7.14.0 stability=stable
diff --git a/specification/security/saml_invalidate/Request.ts b/specification/security/saml_invalidate/Request.ts
index f0fab7cd4..687efc679 100644
--- a/specification/security/saml_invalidate/Request.ts
+++ b/specification/security/saml_invalidate/Request.ts
@@ -20,6 +20,8 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Invalidate SAML.
+ *
  * Submits a SAML LogoutRequest message to Elasticsearch for consumption.
  * @rest_spec_name security.saml_invalidate
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/security/saml_logout/Request.ts b/specification/security/saml_logout/Request.ts
index dbd847365..672f43f42 100644
--- a/specification/security/saml_logout/Request.ts
+++ b/specification/security/saml_logout/Request.ts
@@ -20,6 +20,8 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Logout of SAML.
+ *
  * Submits a request to invalidate an access token and refresh token.
  * @rest_spec_name security.saml_logout
  * @availability stack since=7.5.0 stability=stable
diff --git a/specification/security/saml_prepare_authentication/Request.ts b/specification/security/saml_prepare_authentication/Request.ts
index 604090cd1..994cf0b91 100644
--- a/specification/security/saml_prepare_authentication/Request.ts
+++ b/specification/security/saml_prepare_authentication/Request.ts
@@ -20,7 +20,9 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Creates a SAML authentication request (<AuthnRequest>) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.
+ * Prepare SAML authentication.
+ *
+ * Creates a SAML authentication request (`<AuthnRequest>`) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.
  * @rest_spec_name security.saml_prepare_authentication
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/saml_service_provider_metadata/Request.ts b/specification/security/saml_service_provider_metadata/Request.ts
index 50deb7df6..3f285b066 100644
--- a/specification/security/saml_service_provider_metadata/Request.ts
+++ b/specification/security/saml_service_provider_metadata/Request.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Create SAML service provider metadata.
+ *
  * Generate SAML metadata for a SAML 2.0 Service Provider.
  * @rest_spec_name security.saml_service_provider_metadata
  * @availability stack since=7.11.0 stability=stable
diff --git a/specification/security/suggest_user_profiles/Request.ts b/specification/security/suggest_user_profiles/Request.ts
index daa720a5b..29cf4d6da 100644
--- a/specification/security/suggest_user_profiles/Request.ts
+++ b/specification/security/suggest_user_profiles/Request.ts
@@ -22,6 +22,8 @@ import { long } from '@_types/Numeric'
 import { Hint } from './types'
 
 /**
+ * Suggest a user profile.
+ *
  * Get suggestions for user profiles that match specified search criteria.
  * @rest_spec_name security.suggest_user_profiles
  * @availability stack since=8.2.0 stability=stable
diff --git a/specification/security/update_api_key/Request.ts b/specification/security/update_api_key/Request.ts
index 117424c44..790d25c1e 100644
--- a/specification/security/update_api_key/Request.ts
+++ b/specification/security/update_api_key/Request.ts
@@ -25,6 +25,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Update an API key.
+ *
  * Updates attributes of an existing API key.
  * Users can only update API keys that they created or that were granted to them.
  * Use this API to update API keys created by the create API Key or grant API Key APIs.
diff --git a/specification/security/update_user_profile_data/Request.ts b/specification/security/update_user_profile_data/Request.ts
index ef6d3d83b..cd03ee460 100644
--- a/specification/security/update_user_profile_data/Request.ts
+++ b/specification/security/update_user_profile_data/Request.ts
@@ -25,7 +25,9 @@ import { Refresh, SequenceNumber } from '@_types/common'
 import { long } from '@_types/Numeric'
 
 /**
- * Updates specific data for the user profile that's associated with the specified unique ID.
+ * Update user profile data.
+ *
+ * Update specific data for the user profile that is associated with a unique ID.
  * @rest_spec_name security.update_user_profile_data
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private