[DOCS] Recommend API service tokens (over file) (#96091)

File based service tokens were added to support orchestration
requirements in environments such as ECE and ECK. Outside of these
environments we recommend that API based tokens are used instead.

Resolves: #83491

docs/reference/commands/service-tokens-command.asciidoc

@@ -16,11 +16,22 @@ bin/elasticsearch-service-tokens
 
 [discrete]
 === Description
+
+NOTE: The recommended way to manage <<service-accounts-tokens,service tokens>>
+is via the <<security-api-create-service-token>> API.
+File based tokens are intended for use with orchestrators such as
+{ece-ref}[{ece}] and {eck-ref}[{eck}]
+
 This command creates a `service_tokens` file in the `$ES_HOME/config` directory
 when you create the first service account token. This file does not exist by
 default. {es} monitors this file for changes and dynamically reloads it.
 
-See <<service-accounts,service accounts>> for more information.
+This command only makes changes to the `service_tokens` file on the local node.
+If the service token will be used to authenticate requests against multiple nodes
+in the cluster then you must copy the `service_tokens` file to each node.
+
+See <<service-accounts,service accounts>> for further information about the
+behaviour of service accounts and the management of service tokens.
 
 IMPORTANT: To ensure that {es} can read the service account token information at
 startup, run `elasticsearch-service-tokens` as the same user you use to run

x-pack/docs/en/security/authentication/service-accounts.asciidoc

@@ -68,26 +68,34 @@ service uses to authenticate with {es}. For a given service account, each token
 must have a unique name. Because tokens include access credentials, they should
 always be kept secret by whichever client is using them.
 
-Service tokens can be backed by either the `service_tokens` file or the
-`.security` index. You can create multiple service tokens for a single
+Service tokens can be backed by either the `.security` index (recommended) or
+the `service_tokens` file. You can create multiple service tokens for a single
 service account, which enables multiple instances of the same service to run
 with different credentials.
 
 You must create a service token to use a service account. You can
 create a service token using either:
 
+* The <<security-api-create-service-token,create service account token API>>,
+which saves the new service token in the `.security` index and returns
+the bearer token in the HTTP response.
 * The <<service-tokens-command,elasticsearch-service-tokens>> CLI tool, which
 saves the new service token in the `$ES_HOME/config/service_tokens` file
 and outputs the bearer token to your terminal
-* The <<security-api-create-service-token,create service account token API>>,
-which saves the new service token in the `.security` index and returns
-the bearer token in the HTTP response
 
-Both of these methods create a service token with a guaranteed secret string
-length of `22`. The minimal, acceptable length of a secret string for a service
-token is `10`. If the secret string doesn't meet this minimal length,
-authentication with {es} will fail without even checking the value of the
-service token.
+We recommend that you create service tokens via the REST API rather than the CLI.
+The API stores service tokens within the `.security` index which means that the
+tokens are available for authentication on all nodes, and will be backed up within
+cluster snapshots.
+The use of the CLI is intended for cases where there is an external orchestration
+process (such as {ece-ref}[{ece}] or {eck-ref}[{eck}]) that will manage the
+creation and distribution of the `service_tokens` file.
+
+Both of these methods (API and CLI) create a service token with a guaranteed
+secret string length of `22`.
+The minimal, acceptable length of a secret string for a service token is `10`.
+If the secret string doesn't meet this minimal length, authentication with {es}
+will fail without even checking the value of the service token.
 
 Service tokens never expire. You must actively
 <<security-api-delete-service-token,delete>> them if they are no longer needed.