Edit security API summaries

lcawl · lcawl · commit 1c7790c02484 · 2024-10-22T13:37:25.000-07:00
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
@@ -258,6 +258,7 @@ lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 mapping-date-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-date-format.html
 mapping-meta-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html
 mapping-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-fields.html
+mapping-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-roles.html
 mapping-settings-limit,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-settings-limit.html
 mapping-source-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-source-field.html
 mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping.html
@@ -573,6 +574,8 @@ security-api-saml-logout,https://www.elastic.co/guide/en/elasticsearch/reference
 security-api-saml-prepare-authentication,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-prepare-authentication.html
 security-api-saml-sp-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-sp-metadata.html
 security-api-ssl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-ssl.html
+security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
+service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html
 set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html
 shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html
 simulate-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-pipeline-api.html
diff --git a/specification/security/activate_user_profile/Request.ts b/specification/security/activate_user_profile/Request.ts
@@ -21,7 +21,8 @@ import { GrantType } from '@security/_types/GrantType'
 import { RequestBase } from '@_types/Base'
 
 /**
- * Creates or updates a user profile on behalf of another user.
+ * Create or update a user profile.
+ * Create or update a user profile on behalf of another user.
  * @rest_spec_name security.activate_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/bulk_delete_role/SecurityBulkDeleteRoleRequest.ts b/specification/security/bulk_delete_role/SecurityBulkDeleteRoleRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
+ * Bulk delete roles.
  * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
  * The bulk delete roles API cannot delete roles that are defined in roles files.
  * @rest_spec_name security.bulk_delete_role
diff --git a/specification/security/bulk_put_role/SecurityBulkPutRoleRequest.ts b/specification/security/bulk_put_role/SecurityBulkPutRoleRequest.ts
@@ -23,6 +23,7 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
+ * Bulk create or update roles.
  * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
  * The bulk create or update roles API cannot update roles that are defined in roles files.
  * @rest_spec_name security.bulk_put_role
diff --git a/specification/security/change_password/SecurityChangePasswordRequest.ts b/specification/security/change_password/SecurityChangePasswordRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Password, Refresh, Username } from '@_types/common'
 
 /**
+ * Change passwords.
+ * Change the passwords of users in the native realm and built-in users.
  * @rest_spec_name security.change_password
  * @availability stack stability=stable
  */
diff --git a/specification/security/clear_api_key_cache/SecurityClearApiKeyCacheRequest.ts b/specification/security/clear_api_key_cache/SecurityClearApiKeyCacheRequest.ts
@@ -21,7 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Evicts a subset of all entries from the API key cache.
+ * Clear the API key cache.
+ * Evict a subset of all entries from the API key cache.
  * The cache is also automatically cleared on state changes of the security index.
  * @rest_spec_name security.clear_api_key_cache
  * @availability stack since=7.10.0 stability=stable
diff --git a/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts b/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts
@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Clear the privileges cache.
+ * Evict privileges from the native application privilege cache.
+ * The cache is also automatically cleared for applications that have their privileges updated.
  * @rest_spec_name security.clear_cached_privileges
  * @availability stack since=7.9.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts b/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Clear the user cache.
+ * Evict users from the user cache. You can completely clear the cache or evict specific users.
  * @rest_spec_name security.clear_cached_realms
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/clear_cached_roles/ClearCachedRolesRequest.ts b/specification/security/clear_cached_roles/ClearCachedRolesRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Clear the roles cache.
+ * Evict roles from the native role cache.
  * @rest_spec_name security.clear_cached_roles
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts b/specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts
@@ -21,9 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Names, Namespace, Service } from '@_types/common'
 
 /**
+ * Clear service account token caches.
+ * Evict a subset of all entries from the service account token caches.
  * @rest_spec_name security.clear_cached_service_tokens
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts b/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts
@@ -25,7 +25,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Create an API key.
- * Creates an API key for access without requiring basic authentication.
+ * Create an API key for access without requiring basic authentication.
  * A successful request returns a JSON structure that contains the API key, its unique id, and its name.
  * If applicable, it also returns expiration information for the API key in milliseconds.
  * NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.
diff --git a/specification/security/create_service_token/CreateServiceTokenRequest.ts b/specification/security/create_service_token/CreateServiceTokenRequest.ts
@@ -21,10 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace, Refresh, Service } from '@_types/common'
 
 /**
- * Creates a service accounts token for access without requiring basic authentication.
+ * Create a service account token.
+ * Create a service accounts token for access without requiring basic authentication.
  * @rest_spec_name security.create_service_token
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-account
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts b/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts
@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Names, Refresh } from '@_types/common'
 
 /**
+ * Delete application privileges.
  * @rest_spec_name security.delete_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 {
   path_parts: {
diff --git a/specification/security/delete_role/SecurityDeleteRoleRequest.ts b/specification/security/delete_role/SecurityDeleteRoleRequest.ts
@@ -21,9 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Name, Refresh } from '@_types/common'
 
 /**
- * Delete roles API.
- *
- * Removes roles in the native realm.
+ * Delete roles.
+ * Remove roles in the native realm.
  * @rest_spec_name security.delete_role
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts b/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts
@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Name, Refresh } from '@_types/common'
 
 /**
+ * Delete role mappings.
  * @rest_spec_name security.delete_role_mapping
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/delete_service_token/DeleteServiceTokenRequest.ts b/specification/security/delete_service_token/DeleteServiceTokenRequest.ts
@@ -21,9 +21,12 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace, Refresh, Service } from '@_types/common'
 
 /**
+ * Delete service account tokens.
+ * Delete service account tokens for a service in a specified namespace.
  * @rest_spec_name security.delete_service_token
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/delete_user/SecurityDeleteUserRequest.ts b/specification/security/delete_user/SecurityDeleteUserRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Delete users.
+ * Delete users from the native realm.
  * @rest_spec_name security.delete_user
  * @availability stack stability=stable
  */
diff --git a/specification/security/disable_user/SecurityDisableUserRequest.ts b/specification/security/disable_user/SecurityDisableUserRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Deactivate users.
+ * Deactivate users in the native realm.
  * @rest_spec_name security.disable_user
  * @availability stack stability=stable
  */
diff --git a/specification/security/disable_user_profile/Request.ts b/specification/security/disable_user_profile/Request.ts
@@ -22,7 +22,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
- * Disables a user profile so it's not visible in user profile searches.
+ * Deactivate a user profile.
+ * Deactivated user profiles are not visible in user profile searches.
  * @rest_spec_name security.disable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/enable_user/SecurityEnableUserRequest.ts b/specification/security/enable_user/SecurityEnableUserRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Activate users.
+ * Activate users in the native realm.
  * @rest_spec_name security.enable_user
  * @availability stack stability=stable
  */
diff --git a/specification/security/enable_user_profile/Request.ts b/specification/security/enable_user_profile/Request.ts
@@ -22,7 +22,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
- * Enables a user profile so it's visible in user profile searches.
+ * Activate a user profile.
+ * Activated user profiles are visible in user profile searches.
  * @rest_spec_name security.enable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/enroll_kibana/Request.ts b/specification/security/enroll_kibana/Request.ts
@@ -20,7 +20,8 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Enables a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.
+ * Enroll Kibana.
+ * Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.
  * @rest_spec_name security.enroll_kibana
  * @availability stack since=8.0.0 stability=stable
  */
diff --git a/specification/security/enroll_node/Request.ts b/specification/security/enroll_node/Request.ts
@@ -20,7 +20,8 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Allows a new node to join an existing cluster with security features enabled.
+ * Enroll a node.
+ * Enroll a new node to allow it to join an existing cluster with security features enabled.
  * @rest_spec_name security.enroll_node
  * @availability stack since=8.0.0 stability=stable
  */
diff --git a/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesRequest.ts b/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesRequest.ts
@@ -20,12 +20,12 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Get builtin privileges API.
- *
- * Retrieves the list of cluster privileges and index privileges that are available in this version of Elasticsearch.
+ * Get builtin privileges.
+ * Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.
  * @rest_spec_name security.get_builtin_privileges
  * @availability stack since=7.3.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_security
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {}
diff --git a/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts b/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts
@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Names } from '@_types/common'
 
 /**
+ * Get application privileges.
  * @rest_spec_name security.get_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 {
   path_parts: {
diff --git a/specification/security/get_role/SecurityGetRoleRequest.ts b/specification/security/get_role/SecurityGetRoleRequest.ts
@@ -21,9 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
- * Get roles API.
- *
- * Retrieves roles in the native realm.
+ * Get roles.
+ * Get roles in the native realm.
  * @rest_spec_name security.get_role
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
diff --git a/specification/security/get_role_mapping/SecurityGetRoleMappingRequest.ts b/specification/security/get_role_mapping/SecurityGetRoleMappingRequest.ts
@@ -21,10 +21,15 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Get role mappings.
+ * Role mappings define which roles are assigned to each user.
+ * The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files.
+ * The get role mappings API cannot retrieve role mappings that are defined in role mapping files.
  * @rest_spec_name security.get_role_mapping
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_security
+ * @ext_doc_id mapping-roles
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/get_service_accounts/GetServiceAccountsRequest.ts b/specification/security/get_service_accounts/GetServiceAccountsRequest.ts
@@ -21,11 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Namespace, Service } from '@_types/common'
 
 /**
- * This API returns a list of service accounts that match the provided path parameter(s).
+ * Get service accounts.
+ * Get a list of service accounts that match the provided path parameters.
  * @rest_spec_name security.get_service_accounts
  * @availability stack since=7.13.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_service_account
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts b/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts
@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace } from '@_types/common'
 
 /**
+ * Get service account credentials.
  * @rest_spec_name security.get_service_credentials
  * @availability stack since=7.13.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {
diff --git a/specification/security/get_token/GetUserAccessTokenRequest.ts b/specification/security/get_token/GetUserAccessTokenRequest.ts
@@ -23,6 +23,8 @@ import { Password, Username } from '@_types/common'
 import { AccessTokenGrantType } from './types'
 
 /**
+ * Get a token.
+ * Create a bearer token for access without requiring basic authentication.
  * @rest_spec_name security.get_token
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
diff --git a/specification/security/get_user/SecurityGetUserRequest.ts b/specification/security/get_user/SecurityGetUserRequest.ts
@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Username } from '@_types/common'
 
 /**
+ * Get users.
+ * Get information about users in the native realm and built-in users.
  * @rest_spec_name security.get_user
  * @availability stack stability=stable
  */
