service account copy edits and cross-refs (#48515)

docs/sources/administration/service-accounts/about-service-accounts.md

@@ -7,26 +7,18 @@ weight: 30
 
 # About service accounts in Grafana
 
-A service account can be used to run automated or compute workloads. Applications use service account tokens to authorize themselves as a service account.
+A service account can be used to run automated workloads in Grafana, like dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications like Terraform with the Grafana API.
 
-> **Note:** Service accounts are available in Grafana 8.5+ as a beta feature, to enable service accounts refer to [Enable service accounts]({{< relref "./enable-service-accounts.md#">}}) section.
+> **Note:** Service accounts are available in Grafana 8.5+ as a beta feature To enable service accounts, refer to [Enable service accounts]({{< relref "./enable-service-accounts.md#">}}) section. Service accounts will eventually replace [API keys]({{< relref "../api-keys/_index.md" >}}) as the primary way to authenticate applications that interact with Grafana.
 
 A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
 
 - Schedule reports for specific dashboards to be delivered on a daily/weekly/monthly basis
 - Define alerts in your system to be used in Grafana
-- Set up an external authentication provider to manage users and permissions across an organization
-- Establish machine-to-machine communication
-- Interact with Grafana without logging in as a user
+- Set up an external SAML authentication provider
+- Interact with Grafana without signing in as a user
 
-You can also use service accounts in combination with fine-grained access control to grant users specific scopes.
-
-You can associate a service account with multiple tokens. This is because a service account:
-
-- can be used by multiple team members and therefore can generate their own token each
-- can be used across multiple tenants and each tenant can have its own token
-
-We recommend the you begin by creating one service account for each use case.
+In [Grafana Enterprise]({{< relref "../../enterprise/_index.md" >}}), you can also use service accounts in combination with [role-based access control]({{< relref "../../enterprise/access-control/about-rbac.md" >}}) to grant very specific permissions to applications that interact with Grafana.
 
 > **Note:** Service accounts can only act in the organization they are created for. If you have the same task that is needed for multiple organizations, we recommend creating service accounts in each organization.
 
@@ -34,11 +26,16 @@ We recommend the you begin by creating one service account for each use case.
 
 ## Service account tokens
 
-A service account token is a generated random string that are an alternative to using passwords for authentication with Grafana, to interact with the Grafana HTTP APIs.
+A service account token is a generated random string that acts as an alternative to a password when authenticating with Grafana's HTTP API.
 
 When you create a service account, you can associate one or more access tokens with it. You can use service access tokens the same way as API Keys, for example to access Grafana HTTP API programmatically.
 
-Service account access tokens inherit permissions from service account directly.
+You can create multiple tokens for the same service account. You might want to do this if:
+
+- multiple applications use the same permissions, but you would like to audit or manage their actions separately.
+- you need to rotate or replace a compromised token.
+
+Service account access tokens inherit permissions from the service account.
 
 ### Service accounts benefits
 

docs/sources/administration/service-accounts/add-service-account-token.md

@@ -7,10 +7,9 @@ weight: 60
 
 # Add a token to a service account in Grafana
 
-A service account token is a randomly generated string that external system use to authenticate into Grafana, and include specific permissions to interact with the Grafana HTTP APIs.
-For more information about service accounts, refer to [About service accounts in Grafana]({{< relref "./about-service-accounts.md">}}).
+A service account token is a generated random string that acts as an alternative to a password when authenticating with Grafana’s HTTP API. For more information about service accounts, refer to [About service accounts in Grafana]({{< relref "./about-service-accounts.md">}}).
 
-You can create a service account token using the Grafana UI or via the API. For more information about creating a service account token via the API, refer to [HTTP API Create service account token]({{< relref "../../http_api/serviceaccount.md#create-service-account-tokens">}}).
+You can create a service account token using the Grafana UI or via the API. For more information about creating a service account token via the API, refer to [Create service account tokens using the HTTP API]({{< relref "../../http_api/serviceaccount.md#create-service-account-tokens">}}).
 
 ## Before you begin
 

docs/sources/administration/service-accounts/create-service-account.md

@@ -9,9 +9,9 @@ keywords:
 
 # Create a service account in Grafana
 
-A service account is a user account that you can use to run automated or compute workloads. For more information about how you can use service accounts, refer to [About service accounts]({{< relref "../service-accounts/about-service-accounts.md#">}}).
+A service account can be used to run automated workloads in Grafana, like dashboard provisioning, configuration, or report generation. For more information about how you can use service accounts, refer to [About service accounts]({{< relref "../service-accounts/about-service-accounts.md#">}}).
 
-For more information about creating service accounts via the API, refer to [Create service account via API]({{< relref "../../http_api/serviceaccount.md#create-service-account">}}).
+For more information about creating service accounts via the API, refer to [Create a service account in the HTTP API]({{< relref "../../http_api/serviceaccount.md#create-service-account">}}).
 
 ## Before you begin
 
@@ -20,7 +20,7 @@ For more information about creating service accounts via the API, refer to [Crea
 
 **To create a service account:**
 
-1. Sign in to Grafana and hover your cursor over the organization icon in the sidebar.
+1. Sign in to Grafana and hover your cursor over the Configuration (cog) icon in the sidebar.
 1. Click **Service accounts**.
 1. Click **New service account**.
 1. Enter a **Display name**.

docs/sources/administration/service-accounts/enable-service-accounts.md

@@ -10,19 +10,19 @@ keywords:
 
 # Enable service accounts in Grafana
 
-Service accounts are available behind the `service-accounts` feature toggle available in Grafana 9.0+.
+Service accounts are available behind the `serviceAccounts` feature toggle, available in Grafana 8.5+.
 
 You can enable service accounts by:
 
 - modifying the Grafana configuration file, or
 - configuring an environment variable
 
-## Enable service accounts with configuration file
+## Enable service accounts in the Grafana configuration file
 
 This topic shows you how to enable service accounts by modifying the Grafana configuration file.
 
 1. Sign in to the Grafana server and locate the configuration file. For more information about finding the configuration file, refer to LINK.
-1. Open the configuration file and locate the [feature toggles] section. In your [config file]({{< relref "../../administration/configuration.md#config-file-locations" >}}), add `serviceAccounts` as a [feature_toggle]({{< relref "../../administration/configuration.md#feature_toggle" >}}).
+2. Open the configuration file and locate the [feature toggles section]({{< relref "../../administration/configuration.md#feature_toggles" >}}). Add `serviceAccounts` as a [feature_toggle]({{< relref "../../administration/configuration.md#feature_toggle" >}}).
 
 ```
 [feature_toggles]
@@ -36,8 +36,6 @@ enable = serviceAccounts
 
 This topic shows you how to enable service accounts by setting environment variables before starting Grafana.
 
-> **Note:** Environment variables override any configuration file settings.
+Follow the instructions to [override configuration with environment variables]({{< relref "../../administration/configuration.md#override-configuration-with-environment-variables" >}}). Set the following environment variable: `GF_FEATURE_TOGGLES_ENABLE = serviceAccounts`.
 
-You can use `GF_FEATURE_TOGGLES_ENABLE = serviceAccounts` environment variable.
-
-For more information regarding on how to setup environment variables refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#override-configuration-with-environment-variables" >}}).
+> **Note:** Environment variables override configuration file settings.